Send and receive messages with the Bot Connector API
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. 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
When the user sends a message to your bot, your bot will receive the message as an Activity object of type message. To create a reply to a user's message, create a new Activity object and start by setting these properties:
| Property | Value |
|---|---|
| conversation | Set this property to the contents of the conversation property in the user's message. |
| from | Set this property to the contents of the recipient property in the user's message. |
| locale | Set this property to the contents of the locale property in the user's message, if specified. |
| recipient | Set this property to the contents of the from property in the user's message. |
| replyToId | Set this property to the contents of the id property in the user's message. |
| type | Set this property to message. |
Next, set the properties that specify the information that you want to communicate to the user. 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
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}
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. In this example request, https://smba.trafficmanager.net/teams represents the base URI; the base URI for requests that your bot issues may be different. For details about setting the base URI, see API Reference.
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"
}
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 isn't 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 isn't a direct reply to any message from the user, issue this request:
POST /v3/conversations/{conversationId}/activities
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.
Note
The Bot Framework doesn't 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.
Tip
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
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.
Note
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. In this example request, https://smba.trafficmanager.net/teams represents the base URI; the base URI for requests that your bot issues may be different. For details about setting the base URI, see API Reference.
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"
}
If the conversation is established with the specified users, the response will contain an ID that identifies the conversation.
{
"id": "abcd1234"
}
Your bot can then use this conversation ID to send a message to the user(s) within the conversation.