How Microsoft Teams bots work

APPLIES TO: SDK v4

This article builds on what you learned in How bots work and Event-driven conversations; you should be familiar with these articles before you continue.

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.

Note

The Bot Framework JavaScript, C#, and Python SDKs will continue to be supported, however, the Java SDK is 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 the Java SDK will continue to function.

For new bot building, consider using Power Virtual Agents and read about choosing the right chatbot solution.

For more information, see The future of bot building.

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 and event 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'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.

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'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.

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

Event types Handler Description
application/vnd.microsoft.meetingEnd OnTeamsMeetingEndAsync The bot is associated with a meeting that just ended.
application/vnd.microsoft.meetingStart OnTeamsMeetingStartAsync 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.

Note

Microsoft Teams platform documentation and Teams JavaScript client library (TeamsJS) refer to task modules as modal dialogs. See Dialogs for more information.

Here's 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.