- Article
- 9 minutes to read
Each message in a conversation is an Activity
object of type messageType: message
. When a user sends a message, Teams posts the message to your bot. Teams sends a JSON object to your bot's messaging endpoint. Your bot examines the message to determine its type and responds accordingly.
Basic conversations are handled through the Bot Framework connector, a single REST API. This API enables your bot to communicate with Teams and other channels. The Bot Builder SDK provides the following features:
- Easy access to the Bot Framework connector.
- Additional functionality to manage conversation flow and state.
- Simple ways to incorporate cognitive services, such as natural language processing (NLP).
Your bot receives messages from Teams using the Text
property and it sends single or multiple message responses to the users.
For more information, see User attribution for bot messages
Receive a message
To receive a text message, use the Text
property of the Activity
object. In the bot's activity handler, use the turn context object's Activity
to read a single message request.
The following code shows an example of receiving a message:
- C#
- TypeScript
- Python
- JSON
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken){ await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);}
Send a message
To send a text message, specify the string you want to send as the activity. In the bot's activity handler, use the turn context object's SendActivityAsync
method to send a single message response. Use the object's SendActivitiesAsync
method to send multiple responses at once.
The following code shows an example of sending a message when a user is added to a conversation:
- C#
- TypeScript
- Python
- JSON
protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken){ await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);}
Note
Message splitting occurs when a text message and an attachment are sent in the same activity payload. This activity is split into separate activities by Microsoft Teams, one with just a text message and the other with an attachment. As the activity is split, you do not receive the message ID in response, which is used to update or delete the message proactively. It is recommended to send separate activities instead of depending on message splitting.
Messages sent between users and bots include internal channel data within the message. This data allows the bot to communicate properly on that channel. The Bot Builder SDK allows you to modify the message structure.
Send suggested actions
Suggested actions enable your bot to present buttons that the user can select to provide input. Suggested actions enhance user experience by enabling the user to answer a question or make a choice with selection of a button, rather than typing a response with a keyboard.The buttons remain visible and accessible to the user in the rich cards even after user makes a selection whereas for suggested actions, buttons aren't available. This prevents the user from selection of stale buttons within a conversation.
To add suggested actions to a message, set the suggestedActions
property of the Activity object to specify the list of CardAction objects that represent the buttons to be presented to the user. For more information, see SugestedActions
The following is an example for implementation and experience of suggested actions:
"suggestedActions": { "actions": [ { "type": "imBack", "title": "Action 1", "value": "Action 1" }, { "type": "imBack", "title": "Action 2", "value": "Action 2" } ], "to": [<list of recepientIds>] }
Note
SuggestedActions
are only supported for one-on-one chat bots and text based messages and not for Adaptive Cards or attachments.- Currently
imBack
is the only supported action type and Teams display up to three suggested actions.
Teams channel data
The channelData
object contains Teams-specific information and is a definitive source for team and channel IDs. Optionally, you can cache and use these IDs as keys for local storage. The TeamsActivityHandler
in the SDK pulls out important information from the channelData
object to make it easily accessible. However, you can always access the original data from the turnContext
object.
The channelData
object isn't included in messages in personal conversations, as these take place outside of a channel.
A typical channelData
object in an activity sent to your bot contains the following information:
eventType
: Teams event type passed only in cases of channel modification events.tenant.id
: Microsoft Azure Active Directory (Azure AD) tenant ID passed in all contexts.team
: Passed only in channel contexts, not in personal chat.id
: GUID for the channel.name
: Name of the team passed only in cases of team rename events.
channel
: Passed only in channel contexts, when the bot is mentioned or for events in channels in teams, where the bot has been added.id
: GUID for the channel.name
: Channel name passed only in cases of channel modification events.
channelData.teamsTeamId
: Deprecated. This property is only included for backward compatibility.channelData.teamsChannelId
: Deprecated. This property is only included for backward compatibility.
Example channelData object (channelCreated event)
The following code shows an example of channelData object:
"channelData": { "eventType": "channelCreated", "tenant": { "id": "72f988bf-86f1-41af-91ab-2d7cd011db47" }, "channel": { "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype", "name": "My New Channel" }, "team": { "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype" }}
Message content
Messages received from or sent to your bot can include different types of message content.
Format | From user to bot | From bot to user | Notes |
---|---|---|---|
Rich text | ✔️ | ✔️ | Your bot can send rich text, pictures, and cards. Users can send rich text and pictures to your bot. |
Pictures | ✔️ | ✔️ | Maximum 1024 × 1024 pixels and 1 MB in PNG, JPEG, or GIF format. Animated GIF isn't supported. |
Cards | ❌ | ✔️ | See the Teams card reference for supported cards. |
Emojis | ✔️ | ✔️ | Teams currently supports emojis through UTF-16, such as U+1F600 for grinning face. |
Notifications to your message
You can also add notifications to your message using the Notification.Alert
property. Notifications alert users about new tasks, mentions, and comments. These alerts are related to what users are working on or what they must look at by inserting a notice into their activity feed. For notifications to trigger from your bot message, set the TeamsChannelData
objects Notification.Alert
property to true. Whether or not a notification is raised depends on the individual user's Teams settings and you can't override these settings. The notification type is either a banner, or both a banner and an email.
Note
The Summary field displays any text from the user as a notification message in the feed.
The following code shows an example of adding notifications to your message:
- C#
- TypeScript
- Python
- JSON
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken){ var message = MessageFactory.Text("You'll get a notification, if you've turned them on."); message.TeamsNotifyUser(); await turnContext.SendActivityAsync(message);}
To enhance your message, you can include pictures as attachments to that message.
Picture messages
Pictures are sent by adding attachments to a message. For more information on attachments, see add media attachments to messages.
Pictures can be at most 1024×1024 MB and 1 MB in PNG, JPEG, or GIF format. Animated GIF isn't supported.
Specify the height and width of each image by using XML. In markdown, the image size defaults to 256×256. For example:
- Use:
<img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
. - Don't use:
![Duck on a rock](http://aka.ms/Fo983c)
.
A conversational bot can include Adaptive Cards that simplify business workflows. Adaptive Cards offer rich customizable text, speech, images, buttons, and input fields.
Adaptive Cards
Adaptive Cards can be authored in a bot and shown in multiple apps such as Teams, your website, and so on. For more information, see Adaptive Cards.
The following code shows an example of sending a simple Adaptive Card:
{ "type": "AdaptiveCard", "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "version": "1.5", "body": [ { "items": [ { "size": "large", "text": " Simple Adaptivecard Example with a Textbox", "type": "TextBlock", "weight": "bolder", "wrap": true }, ], "spacing": "extraLarge", "type": "Container", "verticalContentAlignment": "center" } ]}
Form completion feedback
Form completion message appears in Adaptive Cards while sending a response to the bot. The message can be of two types, error or success:
Error: When a response sent to the bot is unsuccessful, Something went wrong, Try again message appears.
Success: When a response sent to the bot is successful, Your response was sent to the app message appears.
You can select Close or switch chat to dismiss the message.
If you don't want to display the success message, set the attribute
hide
totrue
in themsTeams
feedback
property. Following is an example:"content": { "type": "AdaptiveCard", "title": "Card with hidden footer messages", "version": "1.0", "actions": [ { "type": "Action.Submit", "title": "Submit", "msTeams": { "feedback": { "hide": true } } } ] }
For more information on cards and cards in bots, see cards documentation.
Status code responses
Following are the status codes and their error code and message values:
Status code | Error code and message values | Description |
---|---|---|
403 | Code: ConversationBlockedByUser Message: User blocked the conversation with the bot. | User blocked the bot in 1:1 chat or a channel through moderation settings. |
403 | Code: BotNotInConversationRoster Message: The bot isn't part of the conversation roster. | The bot isn't part of the conversation. |
403 | Code: BotDisabledByAdmin Message: The tenant admin disabled this bot. | Tenant blocked the bot. |
401 | Code: BotNotRegistered Message: No registration found for this bot. | The registration for this bot wasn't found. |
412 | Code: PreconditionFailed Message: Precondition failed, please try again. | A precondition failed on one of our dependencies due to multiple concurrent operations on the same conversation. |
404 | Code: ConversationNotFound Message: Conversation not found. | The conversation wasn't found. |
413 | Code: MessageSizeTooBig Message: Message size too large. | The size on the incoming request was too large. |
429 | Code: Throttled Message: Too many requests. Also returns when to retry after. | Too many requests were sent by the bot. For more information, see rate limit. |
Code sample
Sample name | Description | .NETCore | Node.js | Python |
---|---|---|---|---|
Teams conversation bot | Messaging and conversation event handling. | View | View | View |
Next step
Bot command menus
See also
- Send proactive messages
- Subscribe to conversation events
- Send and receive files through the bot
- Send tenant ID and conversation ID to the request headers of the bot