实现通道特定的功能

项目
10/28/2024

适用于： SDK v4

有些通道提供的功能仅靠消息文本和附件是无法实现的。若要实现特定于通道的功能，可以将本机元数据传递给活动对象的通道数据属性。例如，机器人可使用通道数据属性来指示 Telegram 发送贴纸或指示 Office365 发送电子邮件。

本文介绍如何使用消息活动的通道数据属性来实现此通道特定的功能：

Channel	功能
电子邮件	发送和接收包含正文、主题和重要性元数据的电子邮件。
折线图	发送实现 LINE 特定消息类型的消息。
Teams	处理 Microsoft Teams 消息中的 @-mention。

注意

活动对象的通道数据属性的值是 JSON 对象。因此，本文中的示例显示了各种方案中 channelData JSON 属性的预期格式。要使用 .NET 创建 JSON 对象，请使用 JObject (.NET) 类。

创建自定义电子邮件

要创建自定义电子邮件消息，请将活动 channelData 属性设置为包含以下属性的 JSON 对象：

properties	说明
bccRecipients	添加到邮件“Bcc(密件抄送)”字段的用分号 (;) 分隔的电子邮件地址字符串。
ccRecipients	添加到邮件“Cc(抄送)”字段的用分号 (;) 分隔的电子邮件地址字符串。
htmlBody	用于指定电子邮件正文的 HTML 文档。要了解受支持的 HTML 元素和特性，请参阅通道的相关文档。
importance	电子邮件的重要性级别。有效值为 high、normal 和 low。默认值为 normal。
toRecipients	添加到邮件“收件人”字段的用分号 (;) 分隔的电子邮件地址字符串。

用户和机器人之间的传出和传入消息可能有一个 channelData 活动，其中包含一个 JSON 对象，其属性在上表中指定。以下片段显示了从机器人到用户的传入自定义电子邮件的 channelData 属性的示例。

{
    "type": "ActivityTypes.Message",
    "locale": "en-Us",
    "channelID": "email",
    "fromName": { "id": "mybot@mydomain.com", "name": "My bot"},
    "recipientName": { "id": "joe@otherdomain.com", "name": "Joe Doe"},
    "conversation": { "id": "123123123123", "topic": "awesome chat" },
    "channelData":
    {
        "htmlBody": "<html><body style = \"font-family: Calibri; font-size: 11pt;\" >This is more than awesome.</body></html>",
        "importance": "high",
        "ccRecipients": "Yasemin@adatum.com;Temel@adventure-works.com",
    }
}

创建 LINE 消息

要创建实现 LINE 特定消息类型（如贴纸、模板或打开手机摄像头等 LINE 特定操作类型）的消息，请将活动对象的通道数据属性设置为指定 LINE 消息类型和操作类型的 JSON 对象。

properties	说明
type	LINE 操作/消息类型名称

支持以下 LINE 消息类型：

便签
Imagemap
模板（按钮、确认、轮播）
Flex

以下 LINE 操作可以在消息类型为 JSON 对象的操作字段中指定：

回发
消息
URI
Datetimerpicker
Camera
本机照片
位置

若要详细了解这些 LINE 方法及其参数，请参阅 LINE 机器人 API 文档。

此代码段显示了一个 channelData 属性的示例，该属性指定了通道消息类型 ButtonTemplate 和三种操作类型：“camera“、”cameraRoll“和”datetimepicker"。

"channelData": {
    "type": "template",
    "altText": "This is a buttons template",
    "template": {
        "type": "buttons",
        "thumbnailImageUrl": "https://example.com/bot/images/image.jpg",
        "imageAspectRatio": "rectangle",
        "imageSize": "cover",
        "imageBackgroundColor": "#FFFFFF",
        "title": "Menu",
        "text": "Please select",
        "defaultAction": {
            "type": "uri",
            "label": "View detail",
            "uri": "http://example.com/page/123"
        },
        "actions": [{
                "type": "cameraRoll",
                "label": "Camera roll"
            },
            {
                "type": "camera",
                "label": "Camera"
            },
            {
                "type": "datetimepicker",
                "label": "Select date",
                "data": "storeId=12345",
                "mode": "datetime",
                "initial": "2017-12-25t00:00",
                "max": "2018-01-24t23:59",
                "min": "2017-12-25t00:00"
            }
        ]
    }
}

将机器人添加到 Teams

添加到团队的机器人将成为另一个团队成员，在聊天过程中可以 @mentioned（提到）它们。事实上，机器人只有在 @mentioned 时才会接收消息，因此通道上的其他对话不会被发送给机器人。有关详细信息，请参阅使用 Microsoft Teams 机器人进行通道和组聊天。

由于组或通道中的机器人只有在消息中被提及 (@botname) 时才会响应，因此组通道中的机器人收到的每条消息都包含自己的名字，你必须确保消息解析能处理这一点。此外，机器人还可以分析提到的其他用户，并在其消息中提到用户。

检查和去除 @bot 点名

Mention[] m = sourceMessage.GetMentions();
var messageText = sourceMessage.Text;

for (int i = 0;i < m.Length;i++)
{
    if (m[i].Mentioned.Id == sourceMessage.Recipient.Id)
    {
        //Bot is in the @mention list.
        //The below example will strip the bot name out of the message, so you can parse it as if it wasn't included. Note that the Text object will contain the full bot name, if applicable.
        if (m[i].Text != null)
            messageText = messageText.Replace(m[i].Text, "");
    }
}

var text = message.text;
if (message.entities) {
    message.entities
        .filter(entity => ((entity.type === "mention") && (entity.mentioned.id.toLowerCase() === botId)))
        .forEach(entity => {
            text = text.replace(entity.text, "");
        });
    text = text.trim();
}

重要

除非出于测试目的，否则不建议按 GUID 添加机器人。这会严重限制机器人的功能。应将生产环境中的机器人作为应用的一部分添加到 Teams。请参阅创建机器人以及测试和调试 Microsoft Teams 机器人。

通过