您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

通过机器人连接器 API 发送和接收消息Send and receive messages with the Bot Connector API

Bot Connector 服务可让机器人跨多个通道(例如电子邮件、Slack 等)通信。The Bot Connector service enables a bot to communicate across multiple channels such as Email, Slack, and more. 它通过从机器人到通道以及从通道到机器人的活动中继来简化机器人与用户之间的通信。It facilitates communication between bot and user, by relaying activities from bot to channel and from channel to bot. 每个活动包含用于将消息路由到相应目标的信息,以及有关消息创建者、消息上下文和消息接收者的信息。Every activity contains information used for routing the message to the appropriate destination along with information about who created the message, the context of the message, and the recipient of the message. 本文介绍如何使用 Bot Connector 服务在通道上的机器人与用户之间交换消息活动。This article describes how to use the Bot Connector service to exchange message activities between bot and user on a channel.

回复消息Reply to a message

创建回复Create a reply

当用户向机器人发送消息时,机器人收到的消息是 message 类型的 Activity 对象。When the user sends a message to your bot, your bot will receive the message as an Activity object of type message. 若要创建用户消息的回复,请创建一个新的 Activity 对象,并首先设置以下属性:To create a reply to a user's message, create a new Activity object and start by setting these properties:

propertiesProperty Value
聊天conversation 将此属性设置为用户消息中 conversation 属性的内容。Set this property to the contents of the conversation property in the user's message.
from 将此属性设置为用户消息中 recipient 属性的内容。Set this property to the contents of the recipient property in the user's message.
区域设置locale 将此属性设置为用户消息中 locale 属性的内容(如果已指定)。Set this property to the contents of the locale property in the user's message, if specified.
recipientrecipient 将此属性设置为用户消息中 from 属性的内容。Set this property to the contents of the from property in the user's message.
replyToIdreplyToId 将此属性设置为用户消息中 id 属性的内容。Set this property to the contents of the id property in the user's message.
typetype 将此属性设置为 messageSet this property to message.

接下来,设置用于指定要向用户传达的信息的属性。Next, set the properties that specify the information that you want to communicate to the user. 例如,可以设置 text 属性来指定要在消息中显示的文本,设置 speak 属性来指定机器人要讲出的文本,设置 attachments 属性来指定要包含在消息中的媒体附件或丰富卡片。For example, you can set the text property to specify the text to be displayed in the message, set the speak property to specify text to be spoken by your bot, and set the attachments property to specify media attachments or rich cards to include in the message. 有关常用消息属性的详细信息,请参阅创建消息For detailed information about commonly-used message properties, see Create messages.

发送回复Send the reply

使用传入请求中的 serviceUrl 属性来标识机器人在发出响应时应该使用的基 URIUse the serviceUrl property in the incoming activity to identify the base URI that your bot should use to issue its response.

若要发送回复,请发出以下请求:To send the reply, issue this request:

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

在此请求 URI 中,请将 {conversationId} 替换为(回复)活动中 conversation 对象的 id 属性值,并将 {activityId} 替换为(回复)活动中 replyToId 属性的值。In this request URI, replace {conversationId} with the value of the conversation object's id property within your (reply) Activity and replace {activityId} with the value of the replyToId property within your (reply) Activity. 将请求正文设置为创建用来表示回复的 Activity 对象。Set the body of the request to the Activity object that you created to represent your reply.

以下示例演示了一个向用户消息发送简单纯文本回复的请求。The following example shows a request that sends a simple text-only reply to a user's message. 在此示例请求中,https://smba.trafficmanager.net/apis 表示基本 URI;机器人发出的请求的基本 URI 可能不同。In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. 有关设置基本 URI 的详细信息,请参阅 API 参考For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/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"
}

发送(非回复)消息Send a (non-reply) message

机器人发送的大多数消息是对来自用户的消息的回复。A majority of the messages that your bot sends will be in reply to messages that it receives from the user. 但是,机器人有时需要向聊天活动发送消息,而该消息并不是对来自用户的任何消息的直接回复。However, there may be times when your bot needs to send a message to the conversation that is not a direct reply to any message from the user. 例如,机器人可能需要启动新的聊天主题,或者在聊天结束时发送再见消息。For example, your bot may need to start a new topic of conversation or send a goodbye message at the end of the conversation.

若要向聊天活动发送一条并非直接回复来自用户的任何消息的消息,请发出以下请求:To send a message to a conversation that is not a direct reply to any message from the user, issue this request:

POST /v3/conversations/{conversationId}/activities

在此请求 URI 中,请将 {conversationId} 替换为聊天的 ID。In this request URI, replace {conversationId} with the ID of the conversation.

将请求正文设置为创建用来表示回复的 Activity 对象。Set the body of the request to an Activity object that you create to represent your reply.

备注

Bot Framework 不会对机器人可以发送的消息数量施加任何限制。The Bot Framework does not impose any restrictions on the number of messages that a bot may send. 但是,大多数通道都会强制实施限制,以限制机器人在短时间内发送大量的消息。However, most channels enforce throttling limits to restrict bots from sending a large number of messages in a short period of time. 此外,如果机器人快速连续地发送多条消息,则通道可能无法始终以正确的顺序呈现消息。Additionally, if the bot sends multiple messages in quick succession, the channel may not always render the messages in the proper sequence.

启动会话Start a conversation

有时,机器人需要与一个或多个用户发起聊天。There may be times when your bot needs to initiate a conversation with one or more users. 若要开始与通道上的某个用户聊天,机器人必须知道自身的帐户信息,以及该用户在该通道上的帐户信息。To start a conversation with a user on a channel, your bot must know its account information and the user's account information on that channel.

提示

如果机器人将来可能需要与其用户开始聊天,请缓存用户帐户信息、其他相关信息(例如用户首选项和区域设置),以及服务 URL(用作“开始聊天”请求中的基 URI)。If your bot may need to start conversations with its users in the future, cache user account information, other relevant information such as user preferences and locale, and the service URL (to use as the base URI in the Start Conversation request).

若要开始聊天,请发出以下请求:To start a conversation, issue this request:

POST /v3/conversations

将请求正文设置为指定要包含在聊天中的机器人帐户信息和用户帐户信息的 ConversationParameters 对象。Set the body of the request to a ConversationParameters object that specifies your bot's account information and the account information of the user(s) that you want to include in the conversation.

备注

并非所有通道都支持群组会话。Not all channels support group conversations. 请查阅通道文档,以确定某个通道是否支持群组聊天,并确定某个通道在一个聊天活动中允许的参与者人数上限。Consult the channel's documentation to determine whether a channel supports group conversations and to identify the maximum number of participants that a channel allows in a conversation.

以下示例演示了开始聊天的请求。The following example shows a request that starts a conversation. 在此示例请求中,https://smba.trafficmanager.net/apis 表示基本 URI;机器人发出的请求的基本 URI 可能不同。In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. 有关设置基本 URI 的详细信息,请参阅 API 参考For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/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。If the conversation is established with the specified users, the response will contain an ID that identifies the conversation.

{
    "id": "abcd1234"
}

然后,机器人可以使用此聊天 ID 向聊天的用户发送消息Your bot can then use this conversation ID to send a message to the user(s) within the conversation.

其他资源Additional resources