Best practices and updates for bot lifecycle events in Microsoft Teams
Conversation events provide several opportunities for developers like you to take advantage of and subscribe to as you build your conversational bots for Microsoft Teams. We send notifications to your bot when these event types are triggered, and you can simply capture these in your code to act on them. Developers have utilized conversation update events to deliver more engaging and useful bot experiences, and we’re excited to share that we’ve recently added some new team and channel conversation update event types for you to use! And continuing the momentum of new updates, we’re also happy to share that we’ve created a new event, Installation update, adding another event type for you to use. With many advancements to share, let’s dive right in.
New Conversation update event types to utilize
You can take advantage of several different conversation update event types that are available today for your bot to action on – like triggering a welcome message when your bot is added to a team or triggering a notification when a channel is created, renamed, or deleted. A bot receives a conversation update event when it has been added to a conversation, other members have been added to or removed from a conversation, or conversation metadata has changed – and then it’s up to you how and what your bot responds. We’ve been growing our table of conversation update event types and are excited to share some new ones that you can now access:
- Team Deleted: when a team is deleted
- Team Restored: when a team is restored (note: only tenant admins can restore teams)
- Team Archived/Team Unarchived: when a team was archived/unarchived (note: channel cannot be ‘archived’)
- Channel Restored: channel was restored
Together these events will give you an accurate view of the team and channel lifecycle that you can then use to clean up team data, pause notifications or messages to teams and channels that have been deleted or archived.
We’re excited to see what new capabilities you design with these new event types! Check out the full table of conversation update events available to you today.
Installation update events coming soon!
We’ve just talked through all the updates for conversation update events, but now we’d love to share with you our excitement over installation update events – a new event that you will soon be able to use in your bots! The installation update event is sent to your bot when the bot is installed or uninstalled from a thread. On installation the event is issued with an “action” field set to “add” and when the bot is uninstalled the event is sent with the “action” field set to “remove”. The event is also issued when a bot is added or removed as part of an application upgrade. The action field for the upgrade add scenario is set to “add-upgrade”, and on the contrary for remove it’s set to “remove-upgrade”.
You can use this to event to send an introductory message from your bot on installation and subsequently clean up and delete user/thread data when uninstalled. This can be used to meet privacy and data retention requirements on your side.
{
"action": "add",
"type": "installationUpdate",
"timestamp": "2020-10-20T22:08:07.869Z",
"id": "f:3033745319439849398",
"channelId": "msteams",
"serviceUrl": "https://smba.trafficmanager.net/amer/",
"from": {
"id": "sample id",
"aadObjectId": "sample AAD Object ID"
},
"conversation": {
"isGroup": true,
"conversationType": "channel",
"tenantId": "sample tenant ID",
"id": "sample conversation Id@thread.skype"
},
"recipient": {
"id": "sample reciepent bot ID",
"name": "bot name"
},
"entities": [
{
"locale": "en",
"platform": "Windows",
"type": "clientInfo"
}
],
"channelData": {
"settings": {
"selectedChannel": {
"id": "sample channel ID@thread.skype"
}
},
"channel": {
"id": "sample channel ID"
},
"team": {
"id": "sample team ID"
},
"tenant": {
"id": "sample tenant ID"
},
"source": {
"name": "message"
}
},
"locale": "en"
}
Installation update events are in developer preview today and will be Generally Available in March 2021. To see these events you can move your Teams client to public developer preview, and simply add your app personally or to a team or chat.
Changes to post uninstall behavior for bots in personal scope
Moving forward we’ll also align the post uninstall behavior for bots in the personal scope with the teams and groupChat scopes and you will not be able to send or receive messages after an app has been uninstalled. Your bot will receive a 403 response code to new messages posted by your bot. The 403 response code will have fields telling you the reason behind the it – which is either the app was uninstalled or the bot was blocked. We expect these changes to roll out in the coming few months.
Navigating some common exceptions and tips on error handling
As you begin utilizing these new events, we’ve observed some instances where bots are throwing exceptions upon receiving unexpected events from Teams. A couple reasons why this may be occurring:
- You have built your bot without the Microsoft Bot Framework SDK, and as such the bot throws an exception upon receipt of an unexpected event.
- You built your bot with the Microsoft Bot Framework SDK, and you chose to alter the default event behavior by overriding the base event handle.
It’s important to keep in mind that new events can be added anytime in the future, and your bot will begin to receive them. So you must design for the possibility of receiving unexpected events. If you are using the Bot Framework SDK, your bot will automatically respond with a 200 – OK to any events you do not choose to handle.
What’s next and feedback
We’ll continue to update and enhance our conversation update events to provide you and your bots with an accurate and rich understanding of the conversational and user lifecycle in Teams. Continue to monitor updates made to conversation update events to stay up to date on the latest changes and please do provide feedback on your experience!
Thanks!
Light
Dark