{"id":5797,"date":"2021-02-02T11:05:38","date_gmt":"2021-02-02T19:05:38","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=5797"},"modified":"2021-02-02T11:05:38","modified_gmt":"2021-02-02T19:05:38","slug":"best-practices-and-updates-for-bot-lifecycle-events-in-microsoft-teams","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/best-practices-and-updates-for-bot-lifecycle-events-in-microsoft-teams\/","title":{"rendered":"Best practices and updates for bot lifecycle events in Microsoft Teams"},"content":{"rendered":"<p><a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/bots\/how-to\/conversations\/subscribe-to-conversation-events?tabs=dotnet\">Conversation events<\/a> 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\u2019re excited to share that we\u2019ve recently added some new team and channel conversation update event types for you to use! And continuing the momentum of new updates, we\u2019re also happy to share that we\u2019ve created a new event, Installation update, adding another event type for you to use. With many advancements to share, let\u2019s dive right in.<\/p>\n<h5>New Conversation update event types to utilize<\/h5>\n<p>You can take advantage of several different conversation update event types that are available today for your bot to action on \u2013 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 \u2013 and then it\u2019s up to you how and what your bot responds. We\u2019ve been growing our table of conversation update event types and are excited to share some new ones that you can now access:<\/p>\n<p><!--StartFragment --><\/p>\n<ul>\n<li><span class=\"cf0\">Team Deleted: when a team is deleted\u00a0<\/span><\/li>\n<li><span class=\"cf0\">Team Restored: when a team is restored (note: only tenant admins can restore teams)\u00a0<\/span><\/li>\n<li><span class=\"cf0\">Team Archived\/Team Unarchived: when a team was archived\/unarchived (note: channel cannot be &#8216;archived&#8217;)<\/span><\/li>\n<li><span class=\"cf0\">Channel Restored: channel was restored<\/span><\/li>\n<\/ul>\n<p>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.<\/p>\n<p>We\u2019re excited to see what new capabilities you design with these new event types! <a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/bots\/how-to\/conversations\/subscribe-to-conversation-events?tabs=dotnet\">Check out the full table of conversation update events available to you today<\/a>.<\/p>\n<h5>Installation update events coming soon!<\/h5>\n<p><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\"><span class=\"TrackChangeTextInsertion TrackedChange SCXW191386872 BCX8\"><span class=\"TextRun SCXW191386872 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun SCXW191386872 BCX8\">We\u2019ve just talked through all the updates for conversation update events, but now we\u2019d love<\/span><\/span><\/span><span class=\"TrackChangeTextInsertion TrackedChange SCXW191386872 BCX8\"><span class=\"TextRun SCXW191386872 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun SCXW191386872 BCX8\">\u00a0to share w<\/span><\/span><\/span><span class=\"TrackChangeTextInsertion TrackedChange SCXW191386872 BCX8\"><span class=\"TextRun SCXW191386872 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun SCXW191386872 BCX8\">ith you our excitement over\u00a0<\/span><\/span><\/span><span class=\"TrackChangeTextInsertion TrackedChange SCXW191386872 BCX8\"><span class=\"TrackedChange SCXW191386872 BCX8\"><span class=\"TextRun SCXW191386872 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun CommentStart SCXW191386872 BCX8\">installation update events\u00a0<\/span><\/span><\/span><\/span><span class=\"TrackChangeTextInsertion TrackedChange SCXW191386872 BCX8\"><span class=\"TextRun SCXW191386872 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun SCXW191386872 BCX8\">\u2013 a new event\u00a0<\/span><\/span><\/span><span class=\"TrackChangeTextInsertion TrackedChange SCXW191386872 BCX8\"><span class=\"TextRun SCXW191386872 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun SCXW191386872 BCX8\">that you will soon be able to use in your bots! <\/span><\/span><\/span>The\u00a0<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SpellingErrorV2 SCXW121848821 BCX8\">installation update<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">\u00a0event is sent to your bot when the bot is installed or uninstalled from\u00a0<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">a\u00a0<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">thread.\u00a0<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">On installation the<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\"> event <\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">is issued\u00a0<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">with an \u201c<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">a<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">ction\u201d field set to \u201cadd<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">\u201d and when the bot is uninstalled <\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">the <\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">event<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">\u00a0is\u00a0<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">sent <\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">with the\u00a0<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">\u201c<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">a<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">ction\u201d field set to\u00a0<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">\u201cremove\u201d. The event is also issued when a bot is added or removed as part of an application upgrade<\/span><\/span><span class=\"TextRun SCXW121848821 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW121848821 BCX8\">. The action field for the upgrade add scenario is set to \u201cadd-upgrade\u201d, and on the contrary for remove it\u2019s set to \u201cremove-upgrade\u201d.\u00a0<\/span><\/span><\/p>\n<p>You can use this to event to <strong>send an introductory message from your bot on installation<\/strong> and subsequently <strong>clean up and delete user\/thread data when uninstalled<\/strong>. This can be used to meet privacy and data retention requirements on your side.<\/p>\n<blockquote>\n<pre class=\"\">{ \n  \"action\": \"add\",\u00a0\n  \"type\": \"installationUpdate\",\u00a0\n  \"timestamp\": \"2020-10-20T22:08:07.869Z\",\u00a0\n  \"id\": \"f:3033745319439849398\",\u00a0\n  \"channelId\": \"msteams\",\u00a0\n  \"serviceUrl\": \"https:\/\/smba.trafficmanager.net\/amer\/\",\u00a0\n  \"from\": {\u00a0\n \u00a0\u00a0 \"id\": \"sample id\",\u00a0\n \u00a0\u00a0 \"aadObjectId\": \"sample AAD Object ID\"\u00a0\n  },\n  \"conversation\": {\u00a0\n\u00a0\u00a0\u00a0 \"isGroup\": true,\u00a0\n \u00a0\u00a0 \"conversationType\": \"channel\",\u00a0\n \u00a0\u00a0 \"tenantId\": \"sample tenant ID\",\u00a0\n \u00a0\u00a0 \"id\": \"sample conversation Id@thread.skype\"\u00a0\n  },\u00a0\n\n\u00a0 \"recipient\": {\u00a0\n \u00a0\u00a0 \"id\": \"sample reciepent bot ID\",\u00a0\n \u00a0\u00a0 \"name\": \"bot name\"\u00a0\n  },\u00a0\n\u00a0 \"entities\": [\u00a0\n \u00a0\u00a0 {\u00a0\n \u00a0\u00a0\u00a0\u00a0 \"locale\": \"en\",\u00a0\n \u00a0\u00a0\u00a0\u00a0 \"platform\": \"Windows\",\u00a0\n \u00a0\u00a0\u00a0\u00a0 \"type\": \"clientInfo\"\u00a0\n \u00a0\u00a0 }\u00a0\n  ],\u00a0\n\u00a0 \"channelData\": {\u00a0\n \u00a0\u00a0 \"settings\": {\u00a0\n \u00a0\u00a0\u00a0\u00a0 \"selectedChannel\": {\u00a0\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"id\": \"sample channel ID@thread.skype\"\u00a0\n \u00a0\u00a0\u00a0\u00a0 }\u00a0\n \u00a0\u00a0 },\u00a0\n \u00a0\u00a0 \"channel\": {\u00a0\n \u00a0\u00a0\u00a0\u00a0 \"id\": \"sample channel ID\"\u00a0\n \u00a0\u00a0 },\u00a0\n \u00a0\u00a0 \"team\": {\u00a0\n \u00a0\u00a0\u00a0\u00a0 \"id\": \"sample team ID\"\u00a0\n \u00a0\u00a0 },\u00a0\n \u00a0\u00a0 \"tenant\": {\u00a0\n \u00a0\u00a0\u00a0\u00a0 \"id\": \"sample tenant ID\"\u00a0\n \u00a0\u00a0 },\u00a0\n\u00a0\u00a0\u00a0 \"source\": {\u00a0\n \u00a0\u00a0\u00a0\u00a0 \"name\": \"message\"\u00a0\n \u00a0\u00a0 }\u00a0\n  },\u00a0\n  \"locale\": \"en\"\u00a0\n}<\/pre>\n<\/blockquote>\n<p>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 <a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/resources\/dev-preview\/developer-preview-intro\">public developer preview<\/a>, and simply add your app personally or to a team or chat.<\/p>\n<h5>Changes to post uninstall behavior for bots in personal scope<\/h5>\n<p>Moving forward we&#8217;ll also align the post uninstall behavior for bots in the <a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/bots\/how-to\/conversations\/conversation-basics?tabs=dotnet\">personal scope with the teams and groupChat scopes<\/a> and you will not be able to send or receive messages after an app has been uninstalled. Your bot will receive a <em>403 response code<\/em> to new messages posted by your bot. The 403 response code will have fields telling you the reason behind the it &#8211; which is either the app was uninstalled or the bot was blocked. We expect these changes to roll out in the coming few months.<\/p>\n<p><img decoding=\"async\" class=\"aligncenter wp-image-5886\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2021\/02\/Bot-blocked-1-scaled.png\" alt=\"Image of a blocked bot after uninstall\" width=\"676\" height=\"434\" \/><\/p>\n<h5>Navigating some common exceptions and tips on error handling<\/h5>\n<p>As you begin utilizing these new events, we\u2019ve observed some instances where bots are throwing exceptions upon receiving unexpected events from Teams. A couple reasons why this may be occurring:<\/p>\n<ol>\n<li>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.<\/li>\n<li>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.<\/li>\n<\/ol>\n<p>It\u2019s 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 <strong>200 \u2013 OK<\/strong> to any events you do not choose to handle.<\/p>\n<h5>What&#8217;s next and feedback<\/h5>\n<p>We\u2019ll 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. <a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/bots\/how-to\/conversations\/subscribe-to-conversation-events?tabs=dotnet\">Continue to monitor updates made to conversation update events<\/a> to stay up to date on the latest changes and please do <a href=\"https:\/\/github.com\/MicrosoftDocs\/msteams-docs\/issues\/new?title=&amp;body=%0A%0A%5BEnter%20feedback%20here%5D%0A%0A%0A---%0A%23%23%23%23%20Document%20Details%0A%0A%E2%9A%A0%20*Do%20not%20edit%20this%20section.%20It%20is%20required%20for%20docs.microsoft.com%20%E2%9E%9F%20GitHub%20issue%20linking.*%0A%0A*%20ID%3A%200a6d00a4-dd28-33c4-002e-2e8e7c653ce2%0A*%20Version%20Independent%20ID%3A%200856927a-25f4-b1e0-5f1b-d55dc61796f3%0A*%20Content%3A%20%5BSubscribe%20to%20conversation%20events%20-%20Teams%5D(https%3A%2F%2Fdocs.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fconversations%2Fsubscribe-to-conversation-events%3Ftabs%3Ddotnet)%0A*%20Content%20Source%3A%20%5Bmsteams-platform%2Fbots%2Fhow-to%2Fconversations%2Fsubscribe-to-conversation-events.md%5D(https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmaster%2Fmsteams-platform%2Fbots%2Fhow-to%2Fconversations%2Fsubscribe-to-conversation-events.md)%0A*%20Product%3A%20**msteams**%0A*%20GitHub%20Login%3A%20%40WashingtonKayaker%0A*%20Microsoft%20Alias%3A%20**anclear**\">provide feedback on your experience<\/a>!<\/p>\n<p>Thanks!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>We\u2019re excited to share that we\u2019ve recently added some new team and channel conversation update event types for you to use. We\u2019re also happy to share that we\u2019ve created a new event, Installation update, adding another event type for you to use.<\/p>\n","protected":false},"author":69086,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[128],"tags":[148,37],"class_list":["post-5797","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-teams","tag-apps-in-teams","tag-bot-framework"],"acf":[],"blog_post_summary":"<p>We\u2019re excited to share that we\u2019ve recently added some new team and channel conversation update event types for you to use. We\u2019re also happy to share that we\u2019ve created a new event, Installation update, adding another event type for you to use.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/5797","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69086"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=5797"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/5797\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=5797"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=5797"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=5797"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}