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.
Existing bots built with the Java SDK will continue to function.
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.
When your Teams activity handler–bot receives a message activity, its turn handler routes the incoming message activity to its onMessage 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 dispatchConversationUpdateActivity 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.
When overriding these Teams-specific activity handlers, define your bot logic, then be sure to call next() at the end. By calling next(), you ensure that the next handler is run.
When your Teams activity handler–bot receives a message activity, its turn handler routes the incoming message activity to its onMessageActivity 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 onConversationUpdateActivity 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.
When your Teams activity handler–bot receives a message activity, its turn handler routes the incoming message activity to its on_message_activity 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 on_conversation_update_activity 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.
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.
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.
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.
Developers may handle conversation update activities sent from Microsoft Teams via two methods:
To pass in a callback, use methods that begin with onand end with Event (for example, the onTeamsMembersAddedEvent method).
When creating a derived class, override methods that begin with on and don't end with Event (for example, the onTeamsMembersAdded method).
Developers should use only one of these options: either 1 or 2, and not both for the same activity. Meaning, developers should either pass a callback to the onTeamsMembersAddedEvent method or override the onTeamsMembersAdded method in a derived class, and not do both.
Methods for registering a callback
Below is a list of all of the Teams activity emitters called from the dispatchConversationUpdateActivity method of the Teams activity handler.
EventType
Registration method
Condition
Teams documentation
channelCreated
onTeamsChannelCreatedEvent
Sent whenever a new channel is created in a team your bot is installed in.
By default, calls the ActivityHandler.onMembersAdded 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.
By default, calls the ActivityHandler.onMembersRemoved 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.
By default, calls the ActivityHandler.onMembersAdded 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.
By default, calls the ActivityHandler.onMembersRemoved 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.
By default, calls the base class on_members_added_activity 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.
By default, calls the base class on_members_removed_activity 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.
These are the Teams-specific event activity handlers called from the OnEventActivityAsyncTeams 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.
These are the Teams-specific event activity handlers called from the onEventActivityTeams activity handler.
Event types
Handler
Description
application/vnd.microsoft.meetingEnd
onTeamsMeetingEnd
The bot is associated with a meeting that just ended.
application/vnd.microsoft.meetingStart
onTeamsMeetingStart
The bot is associated with a meeting that just started.
These are the Teams-specific event activity handlers called from the onEventActivityTeams activity handler.
Event types
Handler
Description
application/vnd.microsoft.meetingEnd
onTeamsMeetingEnd
The bot is associated with a meeting that just ended.
application/vnd.microsoft.meetingStart
onTeamsMeetingStart
The bot is associated with a meeting that just started.
These are the Teams-specific event activity handlers called from the on_event_activityTeams activity handler.
Event types
Handler
Description
application/vnd.microsoft.meetingEnd
on_teams_meeting_end_event
The bot is associated with a meeting that just ended.
application/vnd.microsoft.meetingStart
on_teams_meeting_start_event
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.