MS Teams机器人：自适应卡片用户提及功能无法正常工作

嘿，我之前也踩过这个坑！Teams里的自适应卡片提及可不是直接输入@用户名就能生效的，得按照Teams的特定规则来配置，我给你一步步说清楚怎么解决：

问题根源 #

你当前的卡片模板只是用了占位符展示内容，但Teams无法识别这种普通文本里的“提及”——它需要明确的实体定义和特定格式标记，才能把文本关联到具体用户。

解决方案步骤 #

1. 修改自适应卡片模板，添加Teams扩展属性

在你的卡片JSON里，新增msteams属性用来存放提及的用户实体信息，同时在需要提及用户的文本位置，用<at>用户名</at>的格式标记：

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.6",
  "msteams": {
    "entities": "${mentionEntities}"
  },
  "body": [
    {
      "type": "TextBlock",
      "text": "On-call users for: ${shiftDate}",
      "weight": "Bolder",
      "size": "Large",
      "wrap": true
    },
    {
      "type": "TextBlock",
      "text": "Schedule: ${scheduleName}",
      "weight": "Bolder",
      "size": "Medium",
      "wrap": true
    },
    {
      "type": "FactSet",
      "facts": "${data}"
    }
  ]
}

2. 填充提及实体和内容

当机器人准备发送卡片时，需要把两个占位符替换成真实数据：

• ${mentionEntities}：替换为一个数组，每个元素对应一个要提及的用户，结构如下：

  [
    {
      "type": "mention",
      "text": "<at>张三</at>",
      "mentioned": {
        "id": "用户的AAD对象ID",
        "name": "张三"
      }
    }
  ]
  

• ${data}：替换为FactSet的事实数组，其中需要提及用户的value字段要包含<at>用户名</at>，比如：

  [
    {
      "title": "主值班人:",
      "value": "<at>张三</at>"
    },
    {
      "title": "备值班人:",
      "value": "<at>李四</at>"
    }
  ]
  

3. 关键注意事项

• 必须用正确的用户ID：mentioned.id必须是用户的AAD对象ID（可以通过机器人上下文turnContext.Activity.From.Id获取），不能用用户名或其他ID，否则Teams无法定位到用户。
• 格式要严格匹配：<at>标签里的文本必须和mentioned.name完全一致，否则提及可能不生效。
• 确保JSON语法正确：填充后的卡片JSON不能有语法错误（比如遗漏逗号、引号不匹配），否则卡片会无法正常渲染。

填充后的完整示例 #

这里给你一个填充好真实数据的卡片示例，你可以参考：

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.6",
  "msteams": {
    "entities": [
      {
        "type": "mention",
        "text": "<at>张三</at>",
        "mentioned": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "张三"
        }
      },
      {
        "type": "mention",
        "text": "<at>李四</at>",
        "mentioned": {
          "id": "987e6543-e21b-43c2-d123-987654321000",
          "name": "李四"
        }
      }
    ]
  },
  "body": [
    {
      "type": "TextBlock",
      "text": "On-call users for: 2024-05-20",
      "weight": "Bolder",
      "size": "Large",
      "wrap": true
    },
    {
      "type": "TextBlock",
      "text": "Schedule: 周末值班",
      "weight": "Bolder",
      "size": "Medium",
      "wrap": true
    },
    {
      "type": "FactSet",
      "facts": [
        {
          "title": "主值班人:",
          "value": "<at>张三</at>"
        },
        {
          "title": "备值班人:",
          "value": "<at>李四</at>"
        }
      ]
    }
  ]
}

按照这个方式配置后，你发送的自适应卡片里的用户提及应该就能正常触发Teams的@提醒了！

备注：内容来源于stack exchange，提问作者Tirumalesh Y