{"id":10527,"date":"2022-05-23T11:47:29","date_gmt":"2022-05-23T18:47:29","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/?p=10527"},"modified":"2022-06-13T16:24:11","modified_gmt":"2022-06-13T23:24:11","slug":"welcome-messages-and-event-updates-for-apps-in-microsoft-teams","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/welcome-messages-and-event-updates-for-apps-in-microsoft-teams\/","title":{"rendered":"Welcome messages and event updates for apps in Microsoft Teams"},"content":{"rendered":"<p><span data-contrast=\"auto\">Welcome messages from your conversational app are the first thing users see after installation. They play a core part in highlighting your app\u2019s main features, starting the setup flow and onboarding users, and improving activation down the line. Today, we are announcing updates to the <\/span><span data-contrast=\"auto\">installationUpdate<\/span><span data-contrast=\"auto\"> &amp; <\/span><span data-contrast=\"auto\">conversationUpdate<\/span><span data-contrast=\"auto\"> events to help streamline the user installation flow and welcome messages sent by apps.<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<h2>Installation &amp; app configuration<\/h2>\n<p><span data-contrast=\"auto\">In our current installation flow, users are asked to select a <\/span><i><span data-contrast=\"auto\">team <\/span><\/i><span data-contrast=\"auto\">and<\/span><i><span data-contrast=\"auto\"> channel. <\/span><\/i><span data-contrast=\"auto\">\u00a0Immediately after installation, the app is available everywhere within the <\/span><i><span data-contrast=\"auto\">team<\/span><\/i><span data-contrast=\"auto\">. The next step for the user is to set up the app in their <\/span><i><span data-contrast=\"auto\">selected<\/span><\/i><span data-contrast=\"auto\"> channel. However, the apps\u2019 welcome message (with setup instructions) is always sent to the \u2018General\u2019 channel and not to the user selected one. This is a choppy user experience where the user intends to set up the app in their selected channels (\u2018Social\u2019 in the example below) but the welcome message with instructions was sent to General. <\/span><span data-ccp-props=\"{}\"> This model will be updated with changes rolling out in the coming months. With the update, <strong>we<\/strong><b>lcome messages will be automatically routed to the user selected channel<\/b> post installation.\u00a0<\/span><\/p>\n<p style=\"text-align: center;\"><span data-ccp-props=\"{}\">\u00a0<\/span><span data-contrast=\"auto\"><a href=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-1-1.png\"><img decoding=\"async\" class=\"aligncenter wp-image-10562 size-full\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-1-1.png\" alt=\"Image Conversational bots image 1\" width=\"492\" height=\"190\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-1-1.png 492w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-1-1-300x116.png 300w\" sizes=\"(max-width: 492px) 100vw, 492px\" \/><\/a><em><span style=\"font-size: 10pt;\">Figure 1: User selecting the social channel during installation for the Trivia Microsoft Teams app<\/span><\/em><\/span><\/p>\n<p style=\"text-align: center;\"><span data-ccp-props=\"{}\">\n<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><a href=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-2-1.png\"><img decoding=\"async\" class=\"aligncenter wp-image-10561\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-2-1-1024x414.png\" alt=\"Image Conversational bots image 2\" width=\"800\" height=\"323\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-2-1-1024x414.png 1024w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-2-1-300x121.png 300w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-2-1-768x311.png 768w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-2-1-1536x621.png 1536w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-2-1-2048x828.png 2048w\" sizes=\"(max-width: 800px) 100vw, 800px\" \/><\/a><span style=\"font-size: 10pt;\"><em>Figure 2: (Current behavior) Trivia\u2019s welcome message is sent to the \u2018General\u2019 channel<\/em><\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<p>&nbsp;<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-4-1.png\"><img decoding=\"async\" class=\"aligncenter wp-image-10560\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-4-1-1024x417.png\" alt=\"Image Conversational bots image 4\" width=\"800\" height=\"326\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-4-1-1024x417.png 1024w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-4-1-300x122.png 300w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-4-1-768x313.png 768w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-4-1-1536x626.png 1536w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/Conversational-bots_image-4-1-2048x834.png 2048w\" sizes=\"(max-width: 800px) 100vw, 800px\" \/><\/a><\/p>\n<p style=\"text-align: center;\"><em><span style=\"font-size: 10pt;\">Figure 3: Trivia\u2019s welcome message is sent to the user selected \u2018Social \ud83c\udf89\ud83c\udf88\ud83d\ude02\u2019 channel\u00a0<\/span><\/em><\/p>\n<p>&nbsp;<\/p>\n<h2>Changes to Installation events<\/h2>\n<p><span data-contrast=\"auto\">There are two events changing in our upcoming update:<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<ul>\n<li data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"1\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559684&quot;:-2,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;hybridMultilevel&quot;}\" aria-setsize=\"-1\" data-aria-posinset=\"1\" data-aria-level=\"1\"><span data-contrast=\"auto\">installationUpdate<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<li data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"1\" data-list-defn-props=\"{&quot;335552541&quot;:1,&quot;335559684&quot;:-2,&quot;335559685&quot;:720,&quot;335559991&quot;:360,&quot;469769226&quot;:&quot;Symbol&quot;,&quot;469769242&quot;:[8226],&quot;469777803&quot;:&quot;left&quot;,&quot;469777804&quot;:&quot;\uf0b7&quot;,&quot;469777815&quot;:&quot;hybridMultilevel&quot;}\" aria-setsize=\"-1\" data-aria-posinset=\"2\" data-aria-level=\"1\"><span data-contrast=\"auto\">conversationUpdate<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/li>\n<\/ul>\n<p><span data-contrast=\"auto\">Currently, when apps are installed into Microsoft Teams, bots do not receive the user selected channel during app installation. The conversation.id provided in the installationUpdate and conversationUpdate events is always set to team id. As a result, bots don\u2019t have the necessary information to send welcome messages into the user specified channel. This issue is being addressed now.<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<p><span class=\"TextRun SCXW95840231 BCX9\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW95840231 BCX9\">Moving forward, when an app is installed in a team\u2019s context from the client, <\/span><\/span><strong><span class=\"TextRun SCXW95840231 BCX9\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW95840231 BCX9\">the <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">user selected <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">channel id from the installation <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">flow<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\"> will be sent to the bot<\/span><\/span><\/strong><span class=\"TextRun SCXW95840231 BCX9\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW95840231 BCX9\"> set as the conversation.id for both activities above.<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\"> A newly created field for <\/span><span class=\"NormalTextRun SpellingErrorV2Themed SCXW95840231 BCX9\">selectedChannel<\/span> <span class=\"NormalTextRun SCXW95840231 BCX9\">will<\/span> <span class=\"NormalTextRun SCXW95840231 BCX9\">also <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">provide<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\"> the<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\"> same channel id. <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">Previously, apps <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">didn\u2019t<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\"> know where users <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">intended to use them <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">and <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">now,<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\"> they do<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">. So, <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">the user selected channel can be thought of as a default channel <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">for <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">the app<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\"> and <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">can be used for <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">a broad<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\"> range of <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">app <\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">scenario<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">s<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">.<\/span><span class=\"NormalTextRun SCXW95840231 BCX9\">\u00a0<\/span><\/span><span class=\"EOP SCXW95840231 BCX9\" data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<h3>Sample payloads:<\/h3>\n<h4>InstallationUpdate<\/h4>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/MicrosoftTeams-image-3.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-10557\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/MicrosoftTeams-image-3.png\" alt=\"Image MicrosoftTeams image 3\" width=\"631\" height=\"817\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/MicrosoftTeams-image-3.png 631w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/MicrosoftTeams-image-3-232x300.png 232w\" sizes=\"(max-width: 631px) 100vw, 631px\" \/><\/a><\/p>\n<p><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<h4>ConversationUpdate \u2013 Bot Member Added<\/h4>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/MicrosoftTeams-image-2.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-10558\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/MicrosoftTeams-image-2.png\" alt=\"Image MicrosoftTeams image 2\" width=\"602\" height=\"699\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/MicrosoftTeams-image-2.png 602w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2022\/05\/MicrosoftTeams-image-2-258x300.png 258w\" sizes=\"(max-width: 602px) 100vw, 602px\" \/><\/a><\/p>\n<p><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<h2>Impact on bots<\/h2>\n<p><span data-contrast=\"auto\">No changes are required for bots that currently send welcome messages by replying to either the installationUpdate or conversationUpdate events using the conversation.id. This should be the case for most apps.<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<p><span data-contrast=\"auto\">Bots that are not using the provided conversation.id to send welcome messages in teams can be updated to reply using this value to take advantage of this change. Team.id can still be explicitly mentioned if your app needs to reference the general channel.<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<h2>What\u2019s next and feedback<\/h2>\n<p><span data-contrast=\"auto\">We are continually making updates and enhancements to our update events to provide you and your app with an accurate and rich understanding of the user lifecycle in Teams.\n<\/span><a href=\"https:\/\/docs.microsoft.com\/en-us\/microsoftteams\/platform\/bots\/how-to\/conversations\/subscribe-to-conversation-events?tabs=dotnet\"><span data-contrast=\"none\">Monitor updates made to conversation update events<\/span><\/a><span data-contrast=\"auto\">\u202fto stay up to date on the latest changes. And please <\/span><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**\"><span data-contrast=\"none\">provide feedback on your experience<\/span><\/a><span data-contrast=\"auto\">!<\/span><span data-ccp-props=\"{}\">\u00a0<\/span><\/p>\n<p>Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Today we\u2019re releasing updates to the installationUpdate &#038; conversationUpdate events to help streamline the user installation flow and welcome messages.<\/p>\n","protected":false},"author":69086,"featured_media":10567,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[128],"tags":[171],"class_list":["post-10527","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-teams","tag-bots"],"acf":[],"blog_post_summary":"<p>Today we\u2019re releasing updates to the installationUpdate &#038; conversationUpdate events to help streamline the user installation flow and welcome messages.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/10527","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=10527"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/10527\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/10567"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=10527"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=10527"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=10527"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}