Bot configuration experience
Bot configuration experience allows users to set up and reconfigure their bots' settings directly within the channel or group chat post-installation, enhancing operational efficiency from the start. This functionality eliminates the need for repeated user interventions that previously hampered timely benefits realization from apps. Users can now tailor the bot to their specific workflows and preferences during installation and reconfigure settings as needed to adapt to changing requirements, ensuring the bot's ongoing relevance and value.
For instance, consider a bot that tracks and shares news topics, or monitors GitHub repositories. Initially configured to align with user workflows, these bots can easily be 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.
Configure
Reconfigure
Build bot configuration experience
Note
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:
Update app manifest
In the app manifest (previously called Teams app manifest) file, update the fetchTask
property under the bots.configuration
object as follows:
"bots": [
{
"botId": "${{AAD_APP_CLIENT_ID}}",
"needsChannelSelector": false,
"scopes": [
"personal",
"team",
"groupChat"
],
"configuration":{
"groupChat":{
"fetchTask": true
},
"team":{
"fetchTask": true
}
},
"isNotificationOnly": false
}
],
For more information, see app manifest schema.
Configure your bot
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
orconfig/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 tocontinue
, 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.protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken) { ConfigResponseBase response = adaptiveCardForContinue(); return Task.FromResult(response); }
type: "auth"
: You can also request the user to authenticate as a response toconfig/fetch
request. Thetype: "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.protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken) { ConfigResponseBase response = new ConfigResponse<BotConfigAuth> { Config = new BotConfigAuth { SuggestedActions = new SuggestedActions { Actions = new List<CardAction> { new CardAction { type: "openUrl", value: "https://example.com/auth", title: "Sign in to this app" } } }, Type = "auth" } };
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.protected override Task<ConfigResponseBase> OnTeamsConfigSubmitAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken) { ConfigResponseBase response = new ConfigResponse<TaskModuleResponseBase> { Config = new TaskModuleMessageResponse { Type = "message", Value = "You have chosen to finish setting up bot" } }; return Task.FromResult(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. |
View | View | View |
Bot configuration app with auth | This sample code describes the configuration and reconfiguration for bots in team and group chat with auth and message response types. |
View | View | View |
Step-by-step guide
Follow the step-by-step guide to configure your bot during installation or after installation from the team or group chat where the bot is installed.