关于Microsoft Teams中Adaptive Cards的头部与通知问题咨询

我正在用Graph API给Microsoft Teams聊天发送Adaptive Cards，参考了官方文档示例，把示例里的application/vnd.microsoft.card.thumbnail换成了application/vnd.microsoft.card.adaptive，还自己用Adaptive Cards工具设计了自定义卡片。现在有两个问题：

1. 发送带Adaptive Card的消息时，卡片被嵌套在一个容器里，不是直接作为整条消息显示。这个头部是哪来的？能不能自定义或者移除？
   

2. 发送HTML消息时，消息内容会显示在toast通知里。能不能给Adaptive Card设置预览或者通知内容？

编辑： 以下是Adaptive Card的JSON代码（发送前会替换{visitorName}和{visitorEmail}变量）：

{
    "type": "AdaptiveCard",
    "backgroundImage": {
        "url": "https://raw.githubusercontent.com/matt-goldman/matt-goldman/main/assets/synth.jpg",
        "fillMode": "Cover",
        "verticalAlignment": "Center",
        "horizontalAlignment": "Center"
    },
    "minHeight": "200px",
    "body": [
        {
            "type": "ColumnSet",
            "columns": [
                {
                    "type": "Column",
                    "width": "stretch",
                    "items": [
                        {
                            "type": "TextBlock",
                            "text": "G'day, you have a visitor!",
                            "wrap": true,
                            "size": "ExtraLarge",
                            "color": "Light",
                            "weight": "Bolder"
                        }
                    ]
                },
                {
                    "type": "Column",
                    "width": "auto",
                    "items": [
                        {
                            "type": "Image",
                            "horizontalAlignment": "Right",
                            "url": "https://github.com/matt-goldman/matt-goldman/raw/main/assets/synth_logo_thumb.png"
                        }
                    ]
                }
            ]
        },
        {
            "type": "TextBlock",
            "text": "**{visitorName}**",
            "wrap": true,
            "color": "Light",
            "size": "ExtraLarge"
        },
        {
            "type": "TextBlock",
            "text": "\n({visitorEmail})\nis here to see you and is waiting in the lobby.",
            "wrap": true,
            "color": "Light",
            "size": "Large"
        }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.4"
}

编辑2： 以下是用Graph SDK for .NET发送卡片的方法，GenerateCardContent方法会返回替换变量后的上述JSON：

public async Task SendNotification(string staffId, string visitorName, string visitorEmail)
{
    
    try
    {
        var chat = new Chat
        {
            ChatType = ChatType.OneOnOne,
            Members = new List<ConversationMember>
            {
                new ConversationMember
                {
                    OdataType = "#microsoft.graph.aadUserConversationMember",
                    Roles = new List<string>
                    {
                        "owner",
                    },
                    AdditionalData = new Dictionary<string, object>
                    {
                        {
                            "user@odata.bind" , $"https://graph.microsoft.com/v1.0/users('{_options.TeamsSenderId}')"
                        },
                    },
                },
                new ConversationMember
                {
                    OdataType = "#microsoft.graph.aadUserConversationMember",
                    Roles = new List<string>
                    {
                        "owner",
                    },
                    AdditionalData = new Dictionary<string, object>
                    {
                        {
                            "user@odata.bind" , $"https://graph.microsoft.com/v1.0/users('{staffId}')"
                        },
                    },
                },
            }
        };

        var teamsChat = await _graphClient.Chats.PostAsync(chat);

        var attachmentGuid = Guid.NewGuid().ToString();

        var message = new ChatMessage
        {
            Body = new ItemBody
            {
                Content = $"<attachment id=\"{attachmentGuid}\"></attachment>",
                ContentType = BodyType.Html,
            },
            Importance = ChatMessageImportance.Normal,
            MessageType = ChatMessageType.Message,
            Locale = "en/AU",
            Attachments = new List<ChatMessageAttachment>
            {
                new ChatMessageAttachment
                {
                    Id = attachmentGuid,
                    ContentType = "application/vnd.microsoft.card.adaptive",
                    ContentUrl = null,
                    Content = GenerateCardContent(visitorName, visitorEmail),
                    Name = null,
                    ThumbnailUrl = null,
                },
            }
        };

        var msg = await _teamsSenderClient.Chats[teamsChat.Id].Messages.PostAsync(message);

        Console.WriteLine($"[GraphService] Sent message: {msg.Id}");
    }
    catch (Exception ex)
    {
        _logger.LogError("Error sending visitor notification", ex);
        throw;
    }
}

1. 移除Adaptive Card的嵌套容器头部 #

你看到的嵌套容器是因为当前消息同时设置了Body（包含<attachment>标签）和Attachments，Teams会把卡片当作普通附件渲染，自动添加默认容器。要让卡片直接作为整条消息显示，只需移除Body的设置，让Adaptive Card成为消息的唯一内容即可。

修改后的消息构造代码：

var message = new ChatMessage
{
    Importance = ChatMessageImportance.Normal,
    MessageType = ChatMessageType.Message,
    Locale = "en/AU",
    Attachments = new List<ChatMessageAttachment>
    {
        new ChatMessageAttachment
        {
            Id = attachmentGuid,
            ContentType = "application/vnd.microsoft.card.adaptive",
            Content = GenerateCardContent(visitorName, visitorEmail),
        },
    }
};

2. 为Adaptive Card设置预览/通知内容 #

有两种方式可以设置toast通知内容和聊天预览文本：

方式一：使用ChatMessage的Preview属性 #

在消息对象中添加Preview字段，指定预览文本和可选图片：

var message = new ChatMessage
{
    Importance = ChatMessageImportance.Normal,
    MessageType = ChatMessageType.Message,
    Locale = "en/AU",
    Preview = new ChatMessagePreview
    {
        PreviewText = new ItemBody
        {
            Content = $"你有访客：{visitorName}",
            ContentType = BodyType.Text
        },
        Images = new List<ChatMessageAttachment>
        {
            new ChatMessageAttachment
            {
                ContentType = "image/png",
                ContentUrl = "https://github.com/matt-goldman/matt-goldman/raw/main/assets/synth_logo_thumb.png"
            }
        }
    },
    Attachments = new List<ChatMessageAttachment>
    {
        // 你的Adaptive Card附件
    }
};

方式二：在Adaptive Card中添加msteams扩展属性 #

直接在卡片JSON里定义Teams专属的通知配置：

{
    "type": "AdaptiveCard",
    "backgroundImage": { ... },
    "msteams": {
        "notification": {
            "title": "访客通知",
            "text": $"{visitorName}正在大堂等候"
        }
    },
    // 其他卡片内容
}

两种方式都能让toast通知和聊天列表预览显示你指定的内容。

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