Bot activity handlers

This document builds on the article on how bots work in the core Bot Framework documentation. The primary difference between bots developed for Microsoft Teams and the core Bot Framework is in the features provided in Teams.

An activity handler is used to organize the conversational logic for your bot. Activities are handled in two ways using Teams activity handlers and bot logic. The Teams activity handler adds support for Teams-specific events and interactions. The bot object contains the conversational reasoning or logic for a turn and exposes a turn handler, which is the method that can accept incoming activities from the bot adapter.

Teams activity handlers

Teams activity handler is derived from Microsoft Bot Framework's activity handler. It routes all Teams activities before allowing any non-Teams specific activities to be handled.

When a bot for Teams receives an activity, it's routed to the activity handlers. All activities are routed through one base handler called the turn handler. The turn handler calls the required activity handler to manage any activity received. The Teams bot is derived from TeamsActivityHandler class, which is derived from the Bot Framework's ActivityHandler class.

Note

If the bot activity takes more than 15 seconds to process, Teams send a retry request to bot endpoint. Hence, you'll see duplicate requests in your bot.

Bots are created using the Bot Framework. If the bots receive a message activity, then the turn handler receives a notification of that incoming activity. The turn handler then sends the incoming activity to the OnMessageActivityAsync activity handler. In Teams, this functionality remains the same. If the bot receives a conversation update activity, then the turn handler receives a notification of that incoming activity and sends the incoming activity to OnConversationUpdateActivityAsync. The Teams activity handler first checks for any Teams specific events. If no events are found, it then passes them along to the Bot Framework's activity handler.

In the Teams activity handler class, there are two primary Teams activity handlers, OnConversationUpdateActivityAsync and OnInvokeActivityAsync. OnConversationUpdateActivityAsync routes all conversation update activities and OnInvokeActivityAsync routes all Teams invoke activities.

To implement your logic for Teams specific activity handlers, you must override the methods in your bot as shown in the bot logic section. There's no base implementation for these handlers. Therefore, add the logic that you want in your override.

The code snippets for Teams activity handlers:

OnTeamsChannelCreatedAsync


protected override Task OnTeamsChannelCreatedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            // Code logic here
        }

OnTeamsChannelDeletedAsync


protected override Task OnTeamsChannelDeletedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            // Code logic here
        }

OnTeamsChannelRenamedAsync


protected override Task OnTeamsChannelRenamedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
  {
   // Code logic here
  }

OnTeamsTeamRenamedAsync


protected override Task OnTeamsTeamRenamedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
  {
   // Code logic here
  }

OnTeamsMembersAddedAsync


protected override Task OnTeamsMembersAddedAsync(IList<TeamsChannelAccount> teamsMembersAdded, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
  {
   // Code logic here
  }

OnTeamsMembersRemovedAsync


protected override Task OnTeamsMembersRemovedAsync(IList<TeamsChannelAccount> teamsMembersRemoved, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken);
  {
   // Code logic here
  }

Bot logic

The bot logic processes incoming activities from one or more of your bot channels and in response generates outgoing activities. It's still true of bots derived from the Teams activity handler class, which first checks for Teams activities. After checking for Teams activities, it passes all other activities to the Bot Framework's activity handler.

Core Bot Framework handlers

Note

  • Except for the added and removed members' activities, all the activity handlers described in this section continue to work as they do with a non-Teams bot.
  • onInstallationUpdateActivityAsync() method is used to get Teams Locale while adding the bot to Teams.

Activity handlers are different in context of a team, where a new member is added to the team instead of a message thread.

The list of handlers defined in ActivityHandler includes the following events:

Event Handler Description
Any activity type received OnTurnAsync This method calls one of the other handlers, based on the type of activity received.
Message activity received OnMessageActivityAsync This method can be overridden to handle a Message activity.
Conversation update activity received OnConversationUpdateActivityAsync This method calls a handler if members other than the bot joined or left the conversation, on a ConversationUpdate activity.
Non-bot members joined the conversation OnMembersAddedAsync This method can be overridden to handle members joining a conversation.
Non-bot members left the conversation OnMembersRemovedAsync This method can be overridden to handle members leaving a conversation.
Event activity received OnEventActivityAsync This method calls a handler specific to the event type, on an Event activity.
Token-response event activity received OnTokenResponseEventAsync This method can be overridden to handle token response events.
Non-token-response event activity received OnEventAsync This method can be overridden to handle other types of events.
Other activity type received OnUnrecognizedActivityTypeAsync This method can be overridden to handle any activity type otherwise unhandled.

Teams specific activity handlers

The TeamsActivityHandler extends the list of handlers in the core Bot Framework handlers section to include the following events:

Event Handler Description
channelCreated OnTeamsChannelCreatedAsync This method can be overridden to handle a Teams channel being created. For more information, see channel created in conversation update events.
channelDeleted OnTeamsChannelDeletedAsync This method can be overridden to handle a Teams channel being deleted. For more information, see channel deleted in conversation update events.
channelRenamed OnTeamsChannelRenamedAsync This method can be overridden to handle a Teams channel being renamed. For more information, see channel renamed in conversation update events.
teamRenamed OnTeamsTeamRenamedAsync return Task.CompletedTask; This method can be overridden to handle a Teams team being renamed. For more information, see team renamed in conversation update events.
MembersAdded OnTeamsMembersAddedAsync This method calls the OnMembersAddedAsync method in ActivityHandler. The method can be overridden to handle members joining a team. For more information, see team members added in conversation update events.
MembersRemoved OnTeamsMembersRemovedAsync This method calls the OnMembersRemovedAsync method in ActivityHandler. The method can be overridden to handle members leaving a team. For more information, see team members removed in conversation update events.

Teams invoke activities

The list of Teams activity handlers called from the OnInvokeActivityAsync Teams activity handler includes the following invoke types:

Invoke types Handler Description
CardAction.Invoke OnTeamsCardActionInvokeAsync This method is invoked when a card action invoke activity is received from the connector.
fileConsent/invoke OnTeamsFileConsentAcceptAsync This method is invoked when a file consent card is accepted by the user.
fileConsent/invoke OnTeamsFileConsentAsync This method is invoked when a file consent card activity is received from the connector.
fileConsent/invoke OnTeamsFileConsentDeclineAsync This method is invoked when a file consent card is declined by the user.
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync This method is invoked when an Office 365 connector card action activity is received from the connector.
signin/verifyState OnTeamsSigninVerifyStateAsync This method is invoked when a signIn verify state activity is received from the connector.
task/fetch OnTeamsTaskModuleFetchAsync This method can be overridden in a derived class to provide logic when a task module is fetched.
task/submit OnTeamsTaskModuleSubmitAsync This method can be overridden in a derived class to provide logic when a task module is submitted.

The Invoke activities listed in this section are for conversational bots in Teams. The Bot Framework SDK also supports invoke activities specific to message extensions. For more information, see what are message extensions.


Now that you've familiarized yourself with bot activity handlers, let us see how bots behave differently depending on the conversation and the messages it receives or sends.

Next step

See also