使用 Bot Connector API 來傳送和接收訊息Send and receive messages with the Bot Connector API

Bot Connector 服務可讓 Bot 跨多個通道 (例如電子郵件、Slack 等) 進行通訊。The Bot Connector service enables a bot to communicate across multiple channels such as Email, Slack, and more. 它可藉由轉接從 Bot 至通道和從通道至 Bot 的活動,來協助 Bot 和使用者之間的通訊。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 服務來交換通道上的 Bot 和使用者之間的訊息活動。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 類型的活動物件收到訊息。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:

屬性Property 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.
收件者recipient 將此屬性設為使用者訊息中 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 屬性來指定您 Bot 要說出的文字,並設定 attachments 屬性來指定要包含在訊息中的媒體附件或複合式資訊卡 (Rich Card)。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 屬性以識別基底 URI (您的 Bot 應該使用該 URI 來發出其回應)。Use 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. 將要求的本文設定為您所建立要代表回覆的活動物件。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,您的 Bot 所發出之要求的基底 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

您 Bot 所傳送的大部分訊息,會在它從使用者接收到的回覆訊息中。A majority of the messages that your bot sends will be in reply to messages that it receives from the user. 不過,有時候您的 Bot 可能需要將訊息傳送到並非直接回覆給任何使用者訊息的對話。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. 例如,您的 Bot 可能需要啟動新的對話主題,或在對話結尾傳送再見訊息。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} 取代為對話的識別碼。In this request URI, replace {conversationId} with the ID of the conversation.

將要求的本文設定為您所建立要代表回覆的活動物件。Set the body of the request to an Activity object that you create to represent your reply.

注意

Bot Framework 對於 Bot 可傳送的訊息數目並無任何限制。The Bot Framework does not impose any restrictions on the number of messages that a bot may send. 不過,大部分的通道會強制執行節流限制,限制 Bot 在短時間內傳送大量的訊息。However, most channels enforce throttling limits to restrict bots from sending a large number of messages in a short period of time. 此外,如果 Bot 連續快速地傳送多則訊息,通道可能不一定會依照正確順序轉譯訊息。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

您的 Bot 有時候可能需要起始與一或多位使用者的對話。There may be times when your bot needs to initiate a conversation with one or more users. 若要在通道上開始與使用者對話,您的 Bot 必須知道其帳戶資訊,以及該通道上的使用者帳戶資訊。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.

提示

如果您的 Bot 在未來可能需要開始與其使用者對話,請快取使用者帳戶資訊、其他相關資訊 (例如使用者喜好設定和地區設定) 和服務 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,您的 Bot 所發出之要求的基底 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"
}

如果對話是以指定的使用者所建立,回應就會包含識別對話的識別碼。If the conversation is established with the specified users, the response will contain an ID that identifies the conversation.

{
    "id": "abcd1234"
}

然後,您的 Bot 可以使用這個對話識別碼,將訊息傳送給對話中的使用者。Your bot can then use this conversation ID to send a message to the user(s) within the conversation.

其他資源Additional resources