How Microsoft Teams bots work


This is an introduction that builds on what you learned in the article How bots work and Event-driven conversations; you should be familiar with these articles before reading this.

The primary differences 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.

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 invoke activities.

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 is no base implementation for most of the Teams-specific activity handlers. You will need to override these handler 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, 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 Teams conversation update activities for more details.

To implement your logic for these Teams-specific activity handlers, you will override methods in your bot.

Teams-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 installation update activities

Add a handler for the installation update event to let your bot:

  • Send an introductory message when it is installed on a conversation thread.
  • Clean up user and thread data whit it is 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.

EventType Handler Condition Teams documentation
channelCreated OnTeamsChannelCreatedAsync Sent whenever a new channel is created in a team your bot is installed in. Channel created.
channelDeleted OnTeamsChannelDeletedAsync Sent whenever a channel is deleted in a team your bot is installed in. Channel deleted.
channelRenamed OnTeamsChannelRenamedAsync Sent whenever a channel is renamed in a team your bot is installed in. Channel renamed.
channelRestored OnTeamsChannelRestoredAsync Sent whenever a channel that was previously deleted is restored in a team that your bot is already installed in. Channel restored.
membersAdded OnTeamsMembersAddedAsync By default, calls the ActivityHandler.OnMembersAddedAsync method. Sent the first time your bot is added to a conversation and every time a new user is added to a team or group chat that your bot is installed in. Team members added.
membersRemoved OnTeamsMembersRemovedAsync By default, calls the ActivityHandler.OnMembersRemovedAsync method. Sent if your bot is removed from a team and every time any user is removed from a team that your bot is a member of. Team members removed.
teamArchived OnTeamsTeamArchivedAsync Sent when the team your bot is installed in is archived. Team archived.
teamDeleted OnTeamsTeamDeletedAsync Sent when the team your bot is in has been deleted. Team deleted.
teamRenamed OnTeamsTeamRenamedAsync Sent when the team your bot is in has been renamed. Team renamed.
teamRestored OnTeamsTeamRestoredAsync Sent when a previously deleted team your bot is in is restored. Team restored.
teamUnarchived OnTeamsTeamUnarchivedAsync Sent when the team your bot is installed in is unarchived. Team unarchived.

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 is a list of all of the Teams activity handlers called from the OnInvokeActivityAsync Teams activity handler:

Invoke types Handler Description
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync Teams O365 Connector Card Action.
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.
signin/verifyState OnTeamsSigninVerifyStateAsync Teams Sign in Verify State.
task/fetch OnTeamsTaskModuleFetchAsync Teams Task Module Fetch.
task/submit OnTeamsTaskModuleSubmitAsync Teams Task Module Submit.

Next steps

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