通过Twilio实现WhatsApp Business与MS Teams集成时消息转发失败问题

核心问题定位 #

你通过curl测试webhook正常，说明MS Teams的入站webhook本身配置无误，报错是因为Twilio默认发送的消息 payload 不符合MS Teams入站webhook的格式要求，Teams仅接受适配其规则的JSON结构，无法直接解析Twilio原生的WhatsApp事件数据。 #

分步排查解决步骤 #

• 第一步：确认Teams入站webhook的必填格式要求 #

  Teams通用入站webhook仅支持固定结构的POST请求，你curl测试时默认使用了符合要求的结构，但Twilio原生转发的结构完全不匹配，才返回Bad payload received by generic incoming webhook报错。标准的可接收格式示例如下：

  {
    "type": "message",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "type": "AdaptiveCard",
          "version": "1.2",
          "body": [
            {
              "type": "TextBlock",
              "text": "示例：来自WhatsApp用户13xxxxxx的消息：你好"
            }
          ]
        }
      }
    ]
  }
  

• 第二步：添加Payload转换中间层 #

  不要直接将Teams的webhook地址填入Twilio的webhook配置，需要中间增加一层格式转换逻辑，可使用Twilio Functions、自建服务接口等实现，转换逻辑要完成以下操作：
  1. 接收Twilio推送的WhatsApp事件数据，提取需要的字段：比如Body（消息内容）、From（发送方号码）、MessageSid（消息唯一ID）等
  2. 将提取到的字段按照上面给出的Teams要求的JSON结构拼装
  3. 主动发送POST请求到Teams的webhook地址，请求头Content-Type必须设置为application/json
  4. 给Twilio返回标准的TwiML响应（哪怕是空的<Response/>即可），避免Twilio触发11200错误

• 第三步：验证配置细节 #

  1. 检查转换层的响应速度，如果处理耗时超过15秒，Twilio会判定超时抛出11200错误，需优化逻辑减少响应耗时
  2. 打日志对比转换后发送给Teams的JSON结构，和你curl测试时使用的结构是否完全一致，避免字段名、嵌套层级写错
  3. 确认没有给Teams的webhook请求添加多余的认证头、签名头，Teams入站webhook默认仅校验URL正确性，多余头信息可能触发拦截

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