How Microsoft Teams bots work
APPLIES TO: SDK v4
The primary difference in bots developed for Microsoft Teams is in how activities are handled. The Teams activity handler derives from the activity handler and processes Teams-specific activity types before processing more general activity types.
The Bot Framework Python and Java SDKs are being retired with final long-term support ending in November 2023. Only critical security and bug fixes within this repository will be undertaken. Existing bots built with these SDKs will continue to function.
Teams activity handler
To create a bot for Teams, derive your bot from the Teams activity handler class. When such a bot receives an activity, it routes the activity through various activity handlers. The initial, base handler is the turn handler, and it routes the activity to a handler based on the activity's type. The turn handler calls the handler that is designed to handle the specific type of activity that was received. The Teams activity handler class is derived from the activity handler class. In addition to the activity types that the activity handler can process, the Teams activity handler class includes additional handlers for Teams-specific activities.
A bot that derives from the Teams activity handler is similar to a bot that derives directly from the activity handler class.
However, Teams includes additional information in
conversationUpdate activities and sends Teams-specific
When your Teams activity handler–bot receives a message activity, its turn handler routes the incoming message activity to its
OnMessageActivityAsync handler, similar to how an activity handler–based bot would. However, when your Teams bot receives a conversation update activity, the Teams version of the
OnConversationUpdateActivityAsync handler processes the activity.
There's no base implementation for most of the Teams-specific activity handlers. You'll need to override these handlers and provide appropriate logic for your bot.
All of the activity handlers described in the activity handling section of the Event-driven conversations using an activity handler article will continue to work as they do with a non-Teams bot, except for handling the members added and removed activities, these activities will be different in the context of a team, where the new member is added to the team as opposed to a message thread. For more information, see Teams conversation update activities.
To implement your logic for these Teams-specific activity handlers, you'll override methods in your bot.
The bot logic processes incoming activities from one or more of your bots channels and generates outgoing activities in response. This is still true of bot derived from the Teams activity handler class, which first checks for Teams activities, then passes all other activities to the Bot Framework's activity handler.
Teams installation update activities
Add a handler for the installation update event to let your bot:
- Send an introductory message when it's installed on a conversation thread.
- Clean up user and thread data when it's uninstalled from a thread.
See Installation update event in the Teams docs for more information.
Teams conversation update activities
The following table lists the Teams events that generate a conversation update activity in a bot. The Microsoft Teams Conversation update events article describes how to use each of these events.
Below is a list of all of the Teams activity handlers called from the
OnConversationUpdateActivityAsync method of the Teams activity handler.
||Sent whenever a new channel is created in a team your bot is installed in.||Channel created.|
||Sent whenever a channel is deleted in a team your bot is installed in.||Channel deleted.|
||Sent whenever a channel is renamed in a team your bot is installed in.||Channel renamed.|
||Sent whenever a channel that was previously deleted is restored in a team that your bot is already installed in.||Channel restored.|
||By default, calls the
||Team members added.|
||By default, calls the
||Team members removed.|
||Sent when the team your bot is installed in is archived.||Team archived.|
||Sent when the team your bot is in has been deleted.||Team deleted.|
||Sent when the team your bot is in has been renamed.||Team renamed.|
||Sent when a previously deleted team your bot is in is restored.||Team restored.|
||Sent when the team your bot is installed in is unarchived.||Team unarchived.|
Teams event activities
The following table lists the Teams-specific event activities Teams sends to a bot. The event activities listed are for conversational bots in Teams.
These are the Teams-specific event activity handlers called from the
OnEventActivityAsync Teams activity handler.
||The bot is associated with a meeting that just ended.|
||The bot is associated with a meeting that just started.|
Teams invoke activities
The following table lists the Teams-specific invoke activities Teams sends to a bot. The invoke activities listed are for conversational bots in Teams. The Bot Framework SDK also supports invokes specific to messaging extensions. For more information, see the Teams What are messaging extensions article.
Here's a list of all of the Teams activity handlers called from the
OnInvokeActivityAsync Teams activity handler:
||Teams O365 Connector Card Action.|
||Teams Card Action Invoke.|
||Teams File Consent Accept.|
||Teams File Consent.|
||Teams File Consent.|
||Teams Sign in Verify State.|
||Teams Task Module Fetch.|
||Teams Task Module Submit.|
For building Teams bots, refer to Microsoft Teams Developer documentation.
Submit and view feedback for