Welcome messages from your conversational app are the first thing users see after installation. They play a core part in highlighting your app’s main features, starting the setup flow and onboarding users, and improving activation down the line. Today, we are announcing updates to the installationUpdate & conversationUpdate events to help streamline the user installation flow and welcome messages sent by apps. 

Installation & app configuration

In our current installation flow, users are asked to select a team and channel.  Immediately after installation, the app is available everywhere within the team. The next step for the user is to set up the app in their selected channel. However, the apps’ welcome message (with setup instructions) is always sent to the ‘General’ 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 (‘Social’ in the example below) but the welcome message with instructions was sent to General. This model will be updated with changes rolling out in the coming months. With the update, welcome messages will be automatically routed to the user selected channel post installation. 

 Figure 1: User selecting the social channel during installation for the Trivia Microsoft Teams app

 Figure 2: (Current behavior) Trivia’s welcome message is sent to the ‘General’ channel 

Figure 3: Trivia’s welcome message is sent to the user selected ‘Social 🎉🎈😂’ channel 

Changes to Installation events

There are two events changing in our upcoming update: 

• installationUpdate 
• conversationUpdate 

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’t have the necessary information to send welcome messages into the user specified channel. This issue is being addressed now. 

Moving forward, when an app is installed in a team’s context from the client, the user selected channel id from the installation flow will be sent to the bot set as the conversation.id for both activities above. A newly created field for selectedChannel will also provide the same channel id. Previously, apps didn’t know where users intended to use them and now, they do. So, the user selected channel can be thought of as a default channel for the app and can be used for a broad range of app scenarios.  

Sample payloads:

InstallationUpdate

ConversationUpdate – Bot Member Added

Impact on bots

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. 

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. 

What’s next and feedback

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. Monitor updates made to conversation update events to stay up to date on the latest changes. And please provide feedback on your experience! 

Happy coding!