使用Twilio向WhatsApp发送Hero卡片报错如何解决

基于Bot Framework Node.js SDK开发的聊天机器人完成WhatsApp（Twilio通道）集成后，尝试发送Hero卡片实现按钮交互时触发运行错误，错误信息如下：

Error: TwilioWhatsAppAdapter.parseActivity():
 An activity text or attachment with contentUrl must be specified.

Twilio官方提供的WhatsApp适配器对Bot Framework原生Hero卡片的解析有强制校验规则：

• Hero卡片必须传入带有效contentUrl的媒体附件（通常是公网可访问的HTTPS图片），如果只配置标题、文本和按钮、留空媒体字段，就会直接抛出上述解析错误
• 适配器不会自动将无媒体的Hero卡片转换为WhatsApp支持的原生交互消息格式，不存在隐式转换逻辑

• 补全Hero卡片必填的媒体参数
  给Hero卡片添加公网可访问的HTTPS协议图片，填入卡片的媒体字段（对应contentUrl校验要求），即可通过解析正常下发，参考代码：

  const { MessageFactory, CardFactory } = require('botbuilder');
  
  const interactiveCard = CardFactory.heroCard(
      '功能选择',
      '请点击下方按钮选择需要办理的业务',
      ['https://替换为自己的公网HTTPS图片地址.png'], // 该字段不可留空，否则触发解析错误
      CardFactory.actions([
          { type: 'imBack', title: '业务咨询', value: 'consult' },
          { type: 'imBack', title: '进度查询', value: 'query' }
      ])
  );
  await turnContext.sendActivity(MessageFactory.attachment(interactiveCard));
  

  注意：该方式下发的内容在WhatsApp端会先展示图片、标题、文本，按钮以快速回复形式展示，不会完全对齐其他渠道的Hero卡片排版

• 直接通过channelData传递WhatsApp原生交互结构
  跳过Bot Framework原生卡片封装，直接在活动的channelData字段写入Twilio支持的WhatsApp交互式消息格式，不需要强制附带contentUrl媒体资源，适配稳定性更高，参考代码：

  await turnContext.sendActivity({
      text: '请选择需要的操作',
      channelData: {
          persistentAction: [
              { "type": "reply", "title": "业务咨询", "payload": "consult" },
              { "type": "reply", "title": "进度查询", "payload": "query" }
          ]
      }
  });
  

• 用Suggested Actions实现纯按钮交互
  如果不需要卡片的图文展示效果，直接使用Bot Framework原生的建议动作（Suggested Actions）下发按钮，Twilio适配器对该组件的适配不需要contentUrl参数，不会触发解析错误，参考代码：

  const { MessageFactory } = require('botbuilder');
  const replyMsg = MessageFactory.text('请选择对应操作选项');
  replyMsg.suggestedActions = {
      actions: [
          { type: 'imBack', title: '业务咨询', value: 'consult' },
          { type: 'imBack', title: '进度查询', value: 'query' }
      ],
      to: []
  };
  await turnContext.sendActivity(replyMsg);
  

• WhatsApp单条交互消息最多支持3个按钮，超出数量会被Twilio接口直接拦截
• 卡片使用的图片链接必须是公网可无鉴权访问的HTTPS地址，不支持HTTP链接、内网地址、带权限校验的私有资源地址

内容的提问来源于stack exchange，提问作者hamza khalid