How Microsoft Teams bots work

This is an introduction that builds on what you learned in the article How bots work, you should be familiar with that article before reading this.

The primary differences in bots developed for Microsoft Teams is in how activities are handled. The Microsoft Teams activity handler derives from the Bot Framework's activity handler to route all teams activities before allowing any non-teams specific activities to be handled.

Teams Activity handlers

Just like any other bot, when a bot is designed for Microsoft Teams receives an activity, it passes it on to its activity handlers. Under the covers, there is one base handler called the turn handler, that all activities are routed through. The turn handler calls the required activity handler to handle whatever type of activity was received. Where a bot designed for Microsoft Teams differs is that it is derived from a Teams Activity Handler class that is derived from the Bot Framework's Activity Handler class. The Teams Activity Handler class includes various Microsoft Teams specific activity handlers that will be discussed in this article.

As with any bot created using the Microsoft Bot Framework, if the bot receives a message activity, the turn handler would see that incoming activity and send it to the OnMessageActivityAsync activity handler. This functionality remains the same, however if the bot receives a conversation update activity, the turn handler would see that incoming activity and send it to the OnConversationUpdateActivityAsync Teams activity handler that will first check for any Teams specific events and pass it along to the Bot Framework's activity handler if none are found.

In the Teams activity handler class there are two primary Teams activity handlers, OnConversationUpdateActivityAsync that routes all conversation update activities, and OnInvokeActivityAsync that routes all Teams invoke activities. All of the activity handlers described in the Bot logic section of the How bots work article will continue to work as they do with a non-Teams bot, with the exception of handling the members added and removed activities, these will be different in the context of a team, where the new member is added to the team as opposed to a message thread. See the Teams conversation update activities table in the Bot logic section for more details.

To implement your logic for these Teams specific activity handlers, you will override these methods in your bot as shown in the Bot logic section below. For each of these handlers, there is no base implementation, so just add the logic that you want in your override.

Bot logic

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 conversation update activities

Below is a list of all of the Teams activity handlers called from the OnConversationUpdateActivityAsync Teams activity handler. The Conversation update events article describes how to use each of these events in a bot.

Event Handler Description
channelCreated OnTeamsChannelCreatedAsync Override this to handle a Teams channel being created. For more information see Channel created.
channelDeleted OnTeamsChannelDeletedAsync Override this to handle a Teams channel being deleted. For more information see Channel deleted.
channelRenamed OnTeamsChannelRenamedAsync Override this to handle a Teams channel being renamed. For more information see Channel renamed.
teamRenamed OnTeamsTeamRenamedAsync return Task.CompletedTask; Override this to handle a Teams Team being Renamed. For more information see Team renamed.
MembersAdded OnTeamsMembersAddedAsync Calls the OnMembersAddedAsync method in ActivityHandler. Override this to handle members joining a team. For more information see Team member added.
MembersRemoved OnTeamsMembersRemovedAsync Calls the OnMembersRemovedAsync method in ActivityHandler. Override this to handle members leaving a team. For more information see Team member removed.

Teams invoke activities

Here is a list of all of the Teams activity handlers called from the OnInvokeActivityAsync Teams activity handler:

Invoke types Handler Description
CardAction.Invoke OnTeamsCardActionInvokeAsync Teams Card Action Invoke.
fileConsent/invoke OnTeamsFileConsentAcceptAsync Teams File Consent Accept.
fileConsent/invoke OnTeamsFileConsentAsync Teams File Consent.
fileConsent/invoke OnTeamsFileConsentDeclineAsync Teams File Consent.
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync Teams O365 Connector Card Action.
signin/verifyState OnTeamsSigninVerifyStateAsync Teams Sign in Verify State.
task/fetch OnTeamsTaskModuleFetchAsync Teams Task Module Fetch.
task/submit OnTeamsTaskModuleSubmitAsync Teams Task Module Submit.

The invoke activities listed above are for conversational bots in Teams. The Bot Framework SDK also supports invokes specific to messaging extensions. For more information see What are messaging extensions

Next steps

For building Teams bots, refer to Microsoft Teams Developer documentation.