无法向Teams Webhook发送MessageCards，请求排查问题

核心问题：MessageCards格式不符合规范 #

你的Webhook本身是正常的（能发送简单文本消息），问题出在MessageCards的JSON结构上——Teams对MessageCards的格式有严格的强制要求，和你使用的简单文本payload不属于同一格式体系。

1. 带@符号报错的原因 #

MessageCards里的@提及不能直接写@用户名，必须通过mentions数组定义提及对象，同时在文本中用占位符关联。正确的提及格式示例：

{
  "@type": "MessageCard",
  "@context": "http://schema.org/extensions",
  "title": "测试提及",
  "text": "Hello <at id=\"1\">张三</at>",
  "mentions": [
    {
      "@type": "mention",
      "text": "<at id=\"1\">张三</at>",
      "mentioned": {
        "@type": "user",
        "id": "用户的Teams ID",
        "name": "张三"
      }
    }
  ]
}

直接写@用户名会被判定为格式非法，触发报错。

2. 移除@后仍返回Bad Request的原因 #

即使去掉@，如果MessageCards缺少必填字段或结构错误，依然会请求失败。最基础的合法MessageCards必须包含两个核心字段：

{
  "@type": "MessageCard",
  "@context": "http://schema.org/extensions",
  "title": "测试卡片",
  "text": "卡片内容示例",
  "themeColor": "0078D7"
}

你之前的简单文本payload不需要这些字段，但MessageCards必须严格包含@type和@context，且字段名、结构层级都要完全符合规范。

3. 快速排查步骤 #

• 检查payload是否包含@type: "MessageCard"和@context: "http://schema.org/extensions"，注意大小写和拼写不能出错
• 所有字段需遵循驼峰命名法（比如themeColor而非theme_color）
• 按钮、图片等附加元素必须放在指定数组中（如按钮放在potentialAction数组），不能随意嵌套层级
• 先用JSON校验工具检查payload的语法合法性，避免逗号遗漏、引号不配对等低级错误

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