Universal Action Model响应中@mention功能失效问题

我制作了一张包含@提及和Action.Execute按钮的AdaptiveCard：

• 用Send to conversation API发送到对话时，提及功能正常，用户名可跳转至个人资料；
• 用户点击按钮触发invoke动作调用API后，返回完全相同的卡片，提及却显示为原始文本<at>Hunter Meyer</at>，既不是可点击链接，也没有被正确格式化。

初始发送的卡片结构（Ruby） #

adaptive_card = [
  {
    "contentType" => "application/vnd.microsoft.card.adaptive",
    "content" => {
      "type" => "AdaptiveCard",
      "$schema" => "http://adaptivecards.io/schemas/adaptive-card.json",
      "version" => "1.4",
      "body" => [
        {
          "type" => "TextBlock",
          "text" => "Have you met, <at>Hunter Meyer</at>?"
        },
        {
          "type" => "ActionSet",
          "actions" => [
            {
              "type" => "Action.Execute",
              "verb" => "met_reply",
              "title" => "Yes",
              "data" => {
                "response" => "yes"
              }
            },
            {
              "type" => "Action.Execute",
              "verb" => "met_reply",
              "title" => "No",
              "data" => {
                "response" => "no"
              }
            }
          ]
        }
      ],
      "msteams" => {
        "entities" => [
          {
            "type" => "mention",
            "text" => "<at>Hunter Meyer</at>",
            "mentioned" => {
              "name" => "Hunter Meyer",
              "id" => "<redacted-user-azure-ad-id>"
            }
          }
        ]
      }
    }
  }
]

原回调响应结构（无效） #

{
  statusCode: 200,
  type: "application/vnd.microsoft.card.adaptive",
  value: adaptive_card["content"]
}

解决方案：调整回调响应的实体位置 #

Teams的Universal Action Model规范要求，invoke回调中的提及实体必须放在响应的根级别字段中，而不是嵌套在AdaptiveCard的msteams属性里。修改后的响应结构如下：

# 提取卡片内容并移除内部的msteams字段
card_content = adaptive_card["content"].tap { |card| card.delete("msteams") }
# 提取提及实体
mention_entities = adaptive_card["content"]["msteams"]["entities"]

# 构造符合规范的响应
{
  statusCode: 200,
  type: "application/vnd.microsoft.card.adaptive",
  value: card_content,
  entities: mention_entities
}

原理说明 #

• 初始发送消息时，Send to conversation API允许将提及实体放在Attachment的msteams字段中，Teams客户端能正常解析；
• 但invoke回调的响应遵循Universal Action Model，必须将提及实体提升到响应根级别的entities数组中，客户端才能正确识别并格式化@提及，使其恢复可点击的跳转功能。

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