Bot configuration experience

Article
04/12/2024

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

Graphic shows the process of configuring a bot into a Teams channel.

Reconfigure

Screenshot shows the configuration option for the bot in the message compose area.

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
Configure your bot

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 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.
- C#
- JavaScript
Sample code reference
```
protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = adaptiveCardForContinue();
    return Task.FromResult(response);
}
```
Sample code reference
```
async handleTeamsConfigFetch(_context, _configData) {
    let response = {};
    const adaptiveCard = CardFactory.adaptiveCard(this.adaptiveCardForContinue());
    response = {
       config: {
          value: {
             card: adaptiveCard,
             height: 500,
             width: 600,
             title: 'test card',
          },
          type: 'continue',
       },
    };
    return response;
}
```

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.

C#
JavaScript

Sample code reference

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"
    }
};

Sample code reference

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.

C#
JavaScript

Sample code reference

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);
}

Sample code reference

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.	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.

Bot configuration experience

Build bot configuration experience

Update app manifest

Configure your bot

Best practices

Code sample

Step-by-step guide

See also

Feedback

Additional resources