Bot configuration experience allows users to set up and reconfigure their bots' settings directly within the channel or group chat scope post-installation. This enhances the bot’s operational efficiency from the start. Bot configuration experience eliminates the need for repeated user interventions that previously hampered the timely benefits of apps, affecting user experience.
With the bot configuration experience, you can ensure the bot's ongoing relevance and value as users can:
Tailor the bot to their specific workflows and preferences during installation.
Reconfigure settings to adapt to changing requirements post installation.
For example, a bot that tracks and shares news topics or monitors GitHub repositories can initially be set up to match user workflows. Later, it can be easily reconfigured to respond to new topics or repositories directly from the group chat, streamlining content management and interaction without leaving the Teams environment. This flexible configuration experience significantly enhances user experience and productivity by integrating bots seamlessly into daily operations.
Here's an example, where a user adds the bot to a group chat and then configures it to align with their specific requirements. The user then reconfigures the bot to change the status.
Bot configuration experience is supported only in channel or group chat.
When you build the bot configuration experience, you must ensure that the user must be able to configure a bot on first installation and reconfigure it at any time.
To build the bot configuration experience, follow these steps:
When a user installs the bot in channel or group chat, the fetchTask property in the app manifest file initiates either config/fetch or config/submit as defined in the teamsBot.js file.
If you set the fetchTask property in the app manifest to:
false: The bot doesn't fetch a dialog or an Adaptive Card. Instead, the bot must provide a static dialog or card that is used when the bot is invoked. For more information, see dialogs.
true: The bot initiates either config/fetch or config/submit as defined. When the bot is invoked, you can return an Adaptive Card or a dialog depending on the context provided in channelData and userdata.
The following table lists the response type associated with the invoke requests:
Invoke request
Response type
config/fetch
Type: "continue" or Type = "auth"
config/submit
Type: "continue" or Type: "message"
type: "continue": type: "continue" is used to define a continuation of a dialog or Adaptive Card within a bot configuration. When the type is set to continue, it indicates that the bot is expecting further interaction from the user to continue with the configuration process.
The adaptiveCardForContinue is a custom function that returns the JSON for an Adaptive Card to be used in different stages of a bot’s workflow. These functions are used to return Adaptive Cards for different scenarios based on the user’s interaction with the bot.
When the user submits the configuration, the config/submit invoke is triggered. It reads the user's input and returns a different Adaptive Card. You can also update the bot configuration to return a dialog.
type: "auth": You can also request the user to authenticate as a response to config/fetch request. The type: "auth" configuration prompts the user to sign in through a specified URL, which must be linked to a valid authentication page that can be opened in a browser. Authentication is essential for scenarios where the bot requires the user to be authenticated. It ensures that the user’s identity is verified, maintaining security, and personalized experiences within the bot’s functionality.
Note
For type: "auth" only third party authentication is supported. Single sign-on (SSO) isn't supported. For more information on third party authentication, see add authentication.
async handleTeamsConfigFetch(_context, _configData) {
let response = {};
response = {
config: {
type: "auth",
suggestedActions: {
actions: [{
type: "openUrl",
value: "https://example.com/auth",
title: "Sign in to this app"
}]
},
},
};
return response;
}
type="message": When the type is set to message, it indicates that the bot is sending a simple message back to the user, indicating the end of the interaction or providing information without requiring further input.
async handleTeamsConfigSubmit(context, _configData) {
let response = {};
response = {
config: {
type: 'message',
value: 'You have chosen to finish setting up bot',
},
}
return response;
}
When a user reconfigures the bot, the fetchTask property in the app manifest file initiates config/fetch in the bot logic. The user can reconfigure the bot settings post-installation in two ways:
@mention the bot in the message compose area. Select the Settings option that appears above the message compose area. A dialog appears, update, or changes the bot's configuration settings in the dialog.
Hover over the bot, the bot profile card appears. To update or change the bot's configuration settings, select the settings icon in the bot profile card.
Best practices
If you want to have an individual channel-level configuration of your bot, ensure that you track the configuration as per the channel. Configuration data isn't stored and the invoke payload includes the sufficient channelData.
Provide a clear and user-friendly dialog that prompts the user to enter the required information for the bot to operate properly, such as a URL, an area path, or a dashboard link.
Avoid sending multiple notifications or requests for configuration after the installation, as it might confuse the users.
Code sample
Sample name
Description
.NET
Node.js
Manifest
Bot configuration app
This sample code describes the configuration and reconfiguration for bots in team and group chat with continue and message response types.
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Platform Docs feedback
Platform Docs is an open source project. Select a link to provide feedback:
Demonstrate skills to plan, deploy, configure, and manage Microsoft Teams to focus on efficient and effective collaboration and communication in a Microsoft 365 environment.