使用 Bot Connector API 发送和接收消息

项目
10/28/2024

Bot Connector 服务可让机器人跨多个通道（例如电子邮件、Slack 等）通信。它通过从机器人到通道以及从通道到机器人的活动中继来简化机器人与用户之间的通信。每个活动包含用于将消息路由到相应目标的信息，以及有关消息创建者、消息上下文和消息接收者的信息。本文介绍如何使用 Bot Connector 服务在通道上的机器人与用户之间交换消息活动。

回复消息

创建回复

当用户向机器人发送消息时，机器人收到的消息是 message 类型的 Activity 对象。若要创建用户消息的回复，请创建一个新的 Activity 对象，并首先设置以下属性：

properties	值
聊天	将此属性设置为用户消息中 `conversation` 属性的内容。
从	将此属性设置为用户消息中 `recipient` 属性的内容。
区域设置	将此属性设置为用户消息中 `locale` 属性的内容（如果已指定）。
recipient	将此属性设置为用户消息中 `from` 属性的内容。
replyToId	将此属性设置为用户消息中 `id` 属性的内容。
type	将此属性设置为 message。

接下来，设置用于指定要向用户传达的信息的属性。例如，可以设置 text 属性来指定要在消息中显示的文本，设置 speak 属性来指定机器人要讲出的文本，设置 attachments 属性来指定要包含在消息中的媒体附件或丰富卡片。有关常用消息属性的详细信息，请参阅创建消息。

发送回复

使用传入请求中的 serviceUrl 属性来标识机器人在发出响应时应该使用的基 URI。

若要发送回复，请发出以下请求：

POST /v3/conversations/{conversationId}/activities/{activityId}

在此请求 URI 中，请将 {conversationId} 替换为（回复）活动中 conversation 对象的 id 属性值，并将 {activityId} 替换为（回复）活动中 replyToId 属性的值。将请求正文设置为创建用来表示回复的 Activity 对象。

以下示例演示了一个向用户消息发送简单纯文本回复的请求。在此示例请求中，https://smba.trafficmanager.net/teams 表示基本 URI；机器人发出的请求的基本 URI 可能不同。有关设置基本 URI 的详细信息，请参阅 API 参考。

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723 
Authorization: Bearer ACCESS_TOKEN 
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "Pepper's News Feed"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "Convo1"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "SteveW"
    },
    "text": "My bot's reply",
    "replyToId": "5d5cdc723"
}

发送（不回复）消息

机器人发送的大多数消息是对来自用户的消息的回复。但是，有时机器人需要向对话发送一条消息，而不是直接回复用户的任何消息。例如，机器人可能需要启动新的聊天主题，或者在聊天结束时发送再见消息。

要向对话发送消息，而不是直接回复用户的任何消息，请发出以下请求：

POST /v3/conversations/{conversationId}/activities

在此请求 URI 中，请将 {conversationId} 替换为聊天的 ID。

将请求正文设置为创建用来表示回复的 Activity 对象。

注意

Bot Framework 对机器人可能发送的消息数量没有任何限制。但是，大多数通道都会强制实施限制，以限制机器人在短时间内发送大量的消息。此外，如果机器人快速连续地发送多条消息，则通道可能无法始终以正确的顺序呈现消息。

启动会话

有时，机器人需要与一个或多个用户发起聊天。若要开始与通道上的某个用户聊天，机器人必须知道自身的帐户信息，以及该用户在该通道上的帐户信息。

提示

如果机器人将来可能需要与其用户开始聊天，请缓存用户帐户信息、其他相关信息（例如用户首选项和区域设置），以及服务 URL（用作“开始聊天”请求中的基 URI）。

若要开始聊天，请发出以下请求：

POST /v3/conversations

将请求正文设置为指定要包含在聊天中的机器人帐户信息和用户帐户信息的 ConversationParameters 对象。

注意

并非所有通道都支持群组会话。请查阅通道文档，以确定某个通道是否支持群组聊天，并确定某个通道在一个聊天活动中允许的参与者人数上限。

以下示例演示了开始聊天的请求。在此示例请求中，https://smba.trafficmanager.net/teams 表示基本 URI；机器人发出的请求的基本 URI 可能不同。有关设置基本 URI 的详细信息，请参阅 API 参考。

POST https://smba.trafficmanager.net/teams/v3/conversations 
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "bot": {
        "id": "12345678",
        "name": "bot's name"
    },
    "isGroup": false,
    "members": [
        {
            "id": "1234abcd",
            "name": "recipient's name"
        }
    ],
    "topicName": "News Alert"
}

如果已与指定的用户建立聊天会话，则响应将包含用于标识该聊天的 ID。

{
    "id": "abcd1234"
}

然后，机器人可以使用此聊天 ID 向聊天的用户发送消息。

通过