使用Dialogflow作为Azure聊天机器人后端时是否支持自适应卡片？

问题梳理 #

• 架构组成：前端为Teams端Azure机器人，后端采用Dialogflow做语言处理，消息终结点基于Dialogflow官方Skype集成方案搭建
• 已验证可用能力：意图识别、带按钮/文本/图片的基础Hero Card返回功能均正常
• 待实现目标：将自适应卡片在线设计器生成的payload配置为Dialogflow意图响应后，可在Teams侧正常渲染展示
• 当前依赖版本：
  • botbuilder: ^4.4.0
  • dialogflow: 0.6.0
  • express: ^4.16.4
• 核心疑问：是否需要修改集成代码中的package.json、server.js文件以支持自适应卡片

实操结论 #

必须修改上述两个文件，现有默认代码和依赖版本无法直接支持自适应卡片渲染，按以下步骤调整即可，无需改动现有核心逻辑

1. 更新package.json依赖 #

现有botbuilder 4.4.0版本对高版本自适应卡片的Teams适配存在已知兼容bug，无需升级dialogflow、express主版本避免额外兼容问题，仅调整botbuilder版本、新增自适应卡片基础依赖即可：

"dependencies": {
  "botbuilder": "~4.18.0",
  "dialogflow": "0.6.0",
  "express": "^4.16.4",
  "adaptivecards": "^2.11.0"
}

修改完成后在项目目录执行npm install完成依赖安装。

2. 调整server.js消息响应逻辑 #

官方集成默认代码仅做了Hero Card等基础富卡片的类型映射，没有适配自适应卡片的附件格式，找到代码中处理Dialogflow返回结果、构造Bot Framework回复消息的段落，保留原有Hero Card处理逻辑，补充自适应卡片处理分支：

// 识别Dialogflow自定义payload中的自适应卡片内容
if (dialogflowResponse.payload && dialogflowResponse.payload.adaptiveCard) {
  const cardAttachment = {
    // 必须使用Teams识别的自适应卡片内容类型，填错会直接不渲染
    contentType: 'application/vnd.microsoft.card.adaptive',
    content: dialogflowResponse.payload.adaptiveCard
  };
  reply.attachments = reply.attachments || [];
  reply.attachments.push(cardAttachment);
}

3. Dialogflow侧配置注意事项 #

• 自适应卡片payload不要放在默认文本响应字段，要放在意图的自定义payload区块，外层用adaptiveCard作为键，值直接填设计器导出的完整卡片JSON
• 导出的卡片version字段不要高于1.5，补全必要的msteams适配属性，否则低版本Teams客户端会出现渲染异常
• 不需要修改Azure机器人的应用清单，自适应卡片是Azure Bot默认支持的附件类型，格式正确即可自动透传到Teams端

常见踩坑 #

• 不要把自适应卡片JSON直接塞到消息的text字段，会被当成纯文本展示
• 低版本botbuilder会自动给自适应卡片加冗余外层包装，触发格式校验失败，升级到4.18版本后该问题已修复
• 如果卡片渲染为空白，优先检查payload中是否包含Teams不支持的自适应卡片元素

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