Conversational bots communicate with users through messaging, enabling seamless interactions. It can simulate real life conversations with users through text or voice interactions. You must ensure that bot conversations are interactive, dynamic, adaptive, and user friendly.
Message content
Messages interaction between your bot and user can include different types of message content that:
A conversational bot can include Adaptive Cards that simplify business workflows. Adaptive Cards offer rich customizable text, speech, images, buttons, and input fields. You can author Adaptive Cards in a bot and shown in multiple apps such as Teams, your website, and so on.
In a chat, each message is an Activity object of type messageType: message. When someone sends a message, Microsoft Teams posts it to your bot. Teams sends a JSON object to your bot's messaging endpoint, and it allows only one endpoint for messaging. Your bot then checks the message to figure out its type and responds accordingly.
Basic conversations are managed through the Bot Framework connector, which is a single REST API. This API enables your bot talk to Teams and other channels. The Bot Builder SDK offers the following features:
Easy access to the Bot Framework connector.
Tools to manage conversation flow and state.
Simple ways to add cognitive services, like natural language processing (NLP).
Your bot gets messages from Teams using the Text property and can send back single or multiple responses to users.
To receive a text message, use the Text property of an 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 activity:
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}
async def on_message_activity(self, turn_context: TurnContext):
// Sends a message activity to the sender of the incoming activity.
return await turn_context.send_activity(MessageFactory.text(f"Echo: {turn_context.activity.text}"))
The Read receipts setting in Teams allow the sender of a chat message to be notified when their message was read by the recipient in one-on-one and group chats. After the recipient reads the message, the Seen
appears next to the message. You also have the option to configure your bot to receive read receipt events through the Read receipts setting. The read receipt event helps you enhance user experience in the following ways:
You can configure your bot to send a follow-up message if your app user hasn't read the message in the personal chat.
You can create a feedback loop using read receipts to tune your bot’s experience.
Note
Read receipts are supported only in user to bot chat scenarios.
Read receipts for bots doesn’t support team, channel, and group chat scopes.
If an admin or user disables the Read receipts setting, the bot doesn't receive the read receipt event.
To receive read receipts events for your bot, ensure the following:
Add the RSCChatMessageReadReceipt.Read.Chat permission in the app manifest, as follows:
You can also add RSC permissions through Graph API. For more information, see consentedPermissionSet.
Override the method OnTeamsReadReceiptAsync with IsMessageRead handler.
The IsMessageRead helper method is useful to determine if the message is read by the recipients. If the compareMessageId is less than or equal to the LastReadMessageId, then the message has been read. Override the OnTeamsReadReceiptAsync method to receive read receipts with IsMessageRead helper method:
protected override async Task OnTeamsReadReceiptAsync(ReadReceiptInfo readReceiptInfo, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
var lastReadMessageId = readReceiptInfo.LastReadMessageId;
if (IsMessageRead("{id of the message that you care}", LastReadMessageId))
{
await turnContext.SendActivityAsync(MessageFactory.Text("User read the bot's message"), cancellationToken);
}
}
The following example shows a read receipts event request that a bot receives:
Read receipt admin setting or user setting is turned on for the tenant for the bot to receive the read receipt events. The admin or the user must enable or disable the read receipt setting.
After the bot is enabled in a user to bot chat scenario, the bot promptly receives a read receipt event when the user reads the bot's message. You can track the user engagement by counting the number of events and you can also send a context aware message.
Receive edit message activity
When you edit a message, the bot gets a notification of the edit message activity.
To get an edit message activity notification in a bot, you can override OnTeamsMessageEditAsync handler.
The following is an example of an edit message activity notification using OnTeamsMessageEditAsync when a sent message is edited:
You can either use event function registration or method override method to get activity notifications to handle the message updates using the Bot SDK:
Event function registration:
this.onTeamsMessageEditEvent(async (context, next) => {
let editedMessage = context.activity.text;
await context.sendActivity(`The edited message is ${editedMessage}"`);
next();
})
Method override:
async onTeamsMessageEdit(context) {
let editedMessage = context.activity.text;
await context.sendActivity(`The edited message is ${editedMessage}"`);
}
PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}
{
"type": "message",
"text": "This message has been updated"
}
Send a message
To send a text message, specify the string you want to send as an 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.
The following code shows an example of sending a message when a user is added to a conversation:
protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}
this.onMembersAddedActivity(async (context, next) => {
await Promise.all((context.activity.membersAdded || []).map(async (member) => {
if (member.id !== context.activity.recipient.id) {
// Sends an activity to the sender of the incoming activity.
await context.sendActivity(
`Welcome to the team ${member.givenName} ${member.surname}`
);
}
}));
await next();
});
async def on_members_added_activity(
self, members_added: [ChannelAccount], turn_context: TurnContext
):
for member in teams_members_added:
// Sends a message activity to the sender of the incoming activity.
await turn_context.send_activity(f"Welcome your new team member {member.id}")
return
Message splitting occurs when a text message and an attachment are sent in the same activity payload. Teams splits this activity into two separate activities, one with 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 can be localized to provide personalization. For more information, see localize your app.
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.
Receive undelete message activity
When you undelete a message, the bot gets a notification of the undelete message activity.
To get an undelete message activity notification in a bot, you can override OnTeamsMessageUndeleteAsync handler.
The following is an example of an undelete message activity notification using OnTeamsMessageUndeleteAsync when a deleted message is restored:
You can either use event function registration or method override method to get activity notifications to handle the message updates using the Bot SDK:
Event function registration:
this.onTeamsMessageUndeleteEvent(async (context, next) => {
let undeletedMessage = context.activity.text;
let messageId = context.activity.id;
await context.sendActivity(`Previously the message was deleted. After undeleting, the message is now: "${undeletedMessage}"`);
next();
})
Method override:
async onTeamsMessageUndelete(context) {
let undeletedMessage = context.activity.text;
let messageId = context.activity.id;
await context.sendActivity(`Previously the message was deleted. After undeleting, the message is now: "${undeletedMessage}"`);
}
PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}
{
"type": "message",
"text": "This message has been updated"
}
Receive soft delete message activity
When you soft delete a message, the bot gets a notification of the soft delete message activity.
To get a soft delete message activity notification in a bot, you can override OnTeamsMessageSoftDeleteAsync handler.
The following example shows a soft delete message activity notification using OnTeamsMessageSoftDeleteAsync when a message is soft deleted:
You can either use event function registration or method override method to get activity notifications to handle the message updates using the Bot SDK:
Event function registration:
this.onTeamsMessageSoftDeleteEvent(async (context, next) => {
let messageId = context.activity.id;
await context.sendActivity(`The deleted message id is ${messageId}`);
next();
})
Method override:
async onTeamsMessageSoftDelete(context) {
let messageId = context.activity.id;
await context.sendActivity(`The deleted message id is ${messageId}`);
}
Update and delete messages sent from bot
Important
The code samples in this section are based on version 4.6 and later versions of the Bot Framework SDK. If you are looking for documentation for earlier versions, see the bots - v3 SDK section in the Legacy SDKs folder of the documentation.
Your bot can dynamically update messages after sending them instead of having them as static snapshots of data. Messages can also be deleted using the Bot Framework's DeleteActivity method.
Note
A bot can't update or delete messages sent by the user in Microsoft Teams.
Update messages
You can use dynamic message updates for scenarios, such as poll updates, modifying available actions after a button press, or any other asynchronous state change.
It is not necessary for the new message to match the original in type. For example, if the original message contains an attachment, the new message can be a simple text message.
To update an existing message, pass a new Activity object with the existing activity ID to the UpdateActivityAsync method of the TurnContext class.
// Send initial message
var response = await turnContext.SendActivityAsync(MessageFactory.Attachment(card.ToAttachment()), cancellationToken);
var activityId = response.Id; // Fetch activity id.
// MessageFactory.Text(): Specifies the type of text data in a message attachment.
var newActivity = MessageFactory.Text("The new text for the activity");
newActivity.Id = activityId;
// UpdateActivityAsync(): A method that can participate in update activity events for the current turn.
await turnContext.UpdateActivityAsync(newActivity, cancellationToken);
To update an existing message, pass a new Activity object with the existing activity ID to the updateActivity method of the TurnContext object.
// Send initial message
var message = await context.sendActivity("<Your Message>");
var activityId = message.id; // Fetch activity id.
// MessageFactory.Text(): Specifies the type of text data in a message attachment.
const newActivity = MessageFactory.text('The new text for the activity');
newActivity.id = activityId;
// A method that can participate in update activity events for the current turn.
await turnContext.updateActivity(newActivity);
To update an existing message, pass a new Activity object with the existing activity ID to the update_activity method of the TurnContext class.
# Send initial message
message = await turn_context.send_activity("<Your Message>")
activityId = message.id # Fetch activity id.
# MessageFactory.Text(): Specifies the type of text data in a message attachment.
new_activity = MessageFactory.text("The new text for the activity")
new_activity.id = activity_id
# A method that can participate in update activity events for the current turn.
update_result = await context.update_activity(new_activity)
Note
You can develop Teams apps in any web-programming technology and directly call the Bot Connector service REST APIs. To do so, you need to implement Authentication security procedures with your API requests.
To update an existing activity within a conversation, include the conversationId and activityId in the request endpoint. To complete this scenario, you must cache the activity ID returned by the original post call.
PUT /v3/conversations/{conversationId}/activities/{activityId}
To update existing card on a button selection, pass a new Activity object with updated card and ReplyToId as activity ID to the UpdateActivityAsync method of the TurnContext class.
// Returns a message activity that contains an attachment.
var activity = MessageFactory.Attachment(card.ToAttachment());
activity.Id = turnContext.Activity.ReplyToId;
// A method that can participate in update activity events for the current turn.
await turnContext.UpdateActivityAsync(activity, cancellationToken);
To update existing card on a button selection, pass a new Activity object with updated card and replyToId as activity ID to the updateActivity method of the TurnContext object.
// MessageFactory.attachment(): Returns a message activity that contains an attachment.
const message = MessageFactory.attachment(card);
message.id = context.activity.replyToId;
// updateActivity(): A method that can participate in update activity events for the current turn.
await context.updateActivity(message);
To update existing card on a button click, pass a new Activity object with updated card and reply_to_id as activity ID to the update_activity method of the TurnContext class.
# MessageFactory.attachment(): Returns a message activity that contains an attachment.
updated_activity = MessageFactory.attachment(CardFactory.hero_card(card))
updated_activity.id = turn_context.activity.reply_to_id
# update_activity(): A method that can participate in update activity events for the current turn.
await turn_context.update_activity(updated_activity)
Note
You can develop Teams apps in any web programming technology and directly call the bot connector service REST APIs. To do this, you must implement authentication security procedures with your API requests.
To update an existing activity within a conversation, include the conversationId and activityId in the request endpoint. To complete this scenario, you must cache the activity ID returned by the original post call.
PUT /v3/conversations/{conversationId}/activities/{activityId}
To delete a message, pass that activity's ID to the DeleteActivityAsync method of the TurnContext class.
foreach (var activityId in _list)
{
// When overridden in a derived class, deletes an existing activity in the conversation.
await turnContext.DeleteActivityAsync(activityId, cancellationToken);
}
To delete a message, pass that activity's ID to the deleteActivity method of the TurnContext object.
for (let i = 0; i < activityIds.length; i++) {
// deleteActivity(): deletes an existing activity in the conversation.
await turnContext.deleteActivity(activityIds[i]);
}
An HTTP status code indicating the outcome of the operation. Nothing is specified in the body of the response.
Send suggested actions
The 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.
When the user selects a button, it remains visible and accessible in the rich cards, but not for the suggested actions. This prevents the user from selection of stale buttons within a conversation.
To add suggested actions to a message, set the suggestedActions property of an activity object to specify the list of card action objects that represent the buttons to be presented to the user. For more information, see suggestedActions.
The following is an example for implementation and experience of suggested actions:
The following illustrates an example of suggested actions:
Note
SuggestedActions are only supported for one-on-one chat bots with both text based messages and Adaptive Cards.
SuggestedActions aren't supported for chat bots with attachments for any conversation type.
imBack is the only supported action type and Teams display up to six suggested actions.
Send messages in 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 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:
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 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:
Ensure to handle these errors appropriately in your Teams app. The following table lists the error codes and the descriptions under which the errors are generated:
Status code
Error code and message values
Description
Retry request
Developer action
400
Code: Bad Argument Message: *scenario specific
Invalid request payload provided by the bot. See error message for specific details.
No
Reevaluate request payload for errors. Check returned error message for details.
401
Code: BotNotRegistered Message: No registration found for this bot.
The registration for this bot wasn't found.
No
Verify the bot ID and password. Ensure the bot ID (Microsoft Entra ID) is registered in the Teams Developer Portal or via Azure bot channel registration in Azure with 'Teams' channel enabled.
403
Code: BotDisabledByAdmin Message: The tenant admin disabled this bot
Admin blocked interactions between user and the bot app. Admin needs to allow the app for the user inside of app policies. For more information, see app policies.
No
Stop posting to conversation until interaction with bot is explicitly initiated by a user in the conversation indicating that the bot is no longer blocked.
403
Code: BotNotInConversationRoster Message: The bot isn't part of the conversation roster.
The bot isn't part of the conversation. App needs to be reinstalled in conversation.
No
Before attempting to send another conversation request, wait for an installationUpdate event, which indicates that the bot is added again.
403
Code: ConversationBlockedByUser Message: User blocked the conversation with the bot.
User blocked the bot in personal chat or a channel through moderation settings.
No
Delete the conversation from cache. Stop attempting to post to conversations until interaction with bot is explicitly initiated by a user in the conversation, indicating that the bot is no longer blocked.
403
Code: ForbiddenOperationException Message: Bot isn't installed in user's personal scope
Proactive message is sent by a bot, which isn't installed in a personal scope.
No
Before attempting to send another conversation request, install the app in personal scope.
403
Code: InvalidBotApiHost Message: Invalid bot api host. For GCC tenants, call https://smba.infra.gcc.teams.microsoft.com.
The bot called the public API endpoint for a conversation that belongs to a GCC tenant.
No
Update the service URL for the conversation to https://smba.infra.gcc.teams.microsoft.com and retry the request.
403
Code: NotEnoughPermissions Message: *scenario specific
Bot doesn't have required permissions to perform the requested action.
No
Determine the required action from the error message.
404
Code: ActivityNotFoundInConversation Message: Conversation not found.
The message ID provided couldn't be found in the conversation. Message doesn't exist or it is deleted.
No
Check if message ID sent is an expected value. Remove the ID if it was cached.
404
Code: ConversationNotFound Message: Conversation not found.
Conversation wasn't found as it doesn't exist or is deleted.
No
Check if conversation ID sent is an expected value. Remove the ID if it was cached.
Retry with exponential backoff. If the issue persists, report the issue in developer community.
503
Service is unavailable.
Yes
Retry with exponential backoff. If the issue persists, report the issue in developer community.
504
Gateway Timeout.
Yes
Retry with exponential backoff. If the issue persists, report the issue in developer community.
Status codes retry guidance
The general retry guidance for each status code is listed in the following table, bot must avoid retrying status codes that aren't specified:
Status code
Retry strategy
403
Retry by calling the GCC API https://smba.infra.gcc.teams.microsoft.com for InvalidBotApiHost.
412
Retry using exponential backoff.
429
Retry using Retry-After header to determine the wait time in seconds and in between requests, if available. Otherwise, retry using exponential backoff with thread ID, if possible.
502
Retry using exponential backoff.
503
Retry using exponential backoff.
504
Retry using exponential backoff.
Request headers of the bot
The current outgoing requests to the bot don't contain in the header or URL any information that helps bots route the traffic without unpacking the entire payload. The activities are sent to the bot through a URL similar to https://<your_domain>/api/messages. Requests are received to show the conversation ID and tenant ID in the headers.
Request header fields
Two non-standard request header fields are added to all the requests sent to bots, for both asynchronous flow and synchronous flow. The following table provides the request header fields and their values:
Field key
Value
x-ms-conversation-id
The conversation ID corresponding to the request activity if applicable and confirmed or verified.
x-ms-tenant-id
The tenant ID corresponding to the conversation in the request activity.
If the tenant or conversation ID isn't present in the activity or wasn't validated on the service side, the value is empty.
Receive only at-mentioned messages
To enable your bots to get only those channel or chat messages where your bot is @mentioned, you must filter the messages. Use the following code snippet to enable your bot to receive only those messages where it's @mentioned:
// When ChannelMessage.Read.Group or ChatMessage.Read.Chat RSC is in the app manifest, this method is called even when bot is not @mentioned.
// This code snippet allows the bot to ignore all messages that do not @mention the bot.
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Ignore the message if bot was not mentioned.
// Remove this if block to process all messages received by the bot.
if (!turnContext.Activity.GetMentions().Any(mention => mention.Mentioned.Id.Equals(turnContext.Activity.Recipient.Id, StringComparison.OrdinalIgnoreCase)))
{
return;
}
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(MessageFactory.Text("Using RSC the bot can receive messages across channels or chats in team without being @mentioned."));
}
If you want your bot to receive all messages, then you don't need to filter the @mention messages.
Step-by-step guide
Follow the step-by-step guide to create a Teams conversation bot.
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Platform Docs feedback
Platform Docs is an open source project. Select a link to provide feedback:
Adaptive Cards are platform-agnostic snippets of UI, authored in JSON, that apps and services can openly exchange. When delivered to a specific app, the JSON is transformed into native UI that automatically adapts to its surroundings. It helps design and integrate light-weight UI for all major platforms and frameworks. In this module, you'll learn how to create engaging messages with Adaptive Cards to create Outlook Actionable Messages and conversations in Microsoft Teams.
appears next to the message. You also have the option to configure your bot to receive read receipt events through the Read receipts setting. The read receipt event helps you enhance user experience in the following ways:
