基于Bot Framework+Twilio的WhatsApp bot无法显示Hero card，如何实现带图带按钮卡片？

核心问题原因 #

Bot Framework默认的Hero Card没有适配WhatsApp原生消息格式，Twilio的WhatsApp通道也不会自动完成Hero Card到WhatsApp可识别的交互式消息的转换，所以直接发送Hero Card会出现渲染失败的问题。

实现前提 #

• 你的Twilio账号已完成WhatsApp sender ID备案，无需额外申请交互式消息权限，普通备案账号即可使用卡片功能
• Bot Framework版本需在v4.14及以上，避免通道自定义payload兼容问题

具体实现方案 #

方案1：透传WhatsApp原生交互式消息（兼容性最高） #

直接构造WhatsApp官方要求的卡片结构，通过Bot Framework的ChannelData字段透传给Twilio，平台不会对内容做额外转换，不会出现格式兼容问题：

1. 构造卡片的核心内容，包含图片地址、卡片标题、描述、按钮配置几个部分
2. 把上述内容封装到Twilio可识别的结构中，赋值给回复消息的ChannelData字段
3. 示例代码片段（C#为例）：

var reply = turnContext.Activity.CreateReply();
reply.ChannelData = JObject.FromObject(new
{
    Twilio = new
    {
        Body = "卡片兜底文字，用户设备不支持交互式消息时会显示这段内容",
        MediaUrl = "你的卡片图片公网HTTPS地址",
        Buttons = new[]
        {
            new { Id = "btn_01", Text = "按钮1" },
            new { Id = "btn_02", Text = "按钮2" }
        }
    }
});
await turnContext.SendActivityAsync(reply);

注意：图片地址必须是公网可直接访问的HTTPS地址，不能有访问鉴权，否则WhatsApp无法拉取渲染
单张卡片最多支持3个按钮，每个按钮文字长度不能超过20个字符，超出限制会导致消息发送失败

方案2：使用WhatsApp专属卡片类 #

如果不想手动构造原生payload，可以使用Bot Framework针对WhatsApp通道优化的专属卡片组件：

• 不使用默认的HeroCard，改用WhatsAppCard类（需引入Bot.Builder.ChannelConnector.WhatsApp扩展包）
• 按照要求填充Image、Title、Subtitle、Buttons字段后，直接附加到回复消息的Attachments中即可，Bot Framework会自动完成格式转换

常见排错点 #

• 卡片无法显示时优先检查按钮数量、文字长度、图片地址是否符合WhatsApp限制要求
• 可查看Twilio控制台的WhatsApp消息日志，确认是否存在格式错误类报错
• 不要在卡片中添加Tap action等WhatsApp不支持的Hero Card原生字段，会导致整体渲染失败

内容的提问来源于stack exchange，提问作者sariga ms