Skip to content

Update Teams SDK samples in bot-configuration-experience.md #14250

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Pranjal-MSFT wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Update Teams SDK samples in bot-configuration-experience.md #14250

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0446d5e
Update bot-configuration-experience.md
Pranjal-MSFT Apr 3, 2026
8177dd2
Update bot-configuration-experience.md
Pranjal-MSFT Apr 3, 2026
6483201
Update bot-configuration-experience.md
Pranjal-MSFT Apr 3, 2026
7423ca1
Update bot-configuration-experience.md
Pranjal-MSFT Apr 3, 2026
f194a34
Update bot-configuration-experience.md
Pranjal-MSFT Apr 6, 2026
872b3d2
Update bot-configuration-experience.md
Pranjal-MSFT Apr 9, 2026
96b5ae6
Update bot-configuration-experience.md
Pranjal-MSFT Apr 21, 2026
b1f91c9
Update bot-configuration-experience.md
Pranjal-MSFT Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
307 changes: 197 additions & 110 deletions msteams-platform/bots/how-to/bot-configuration-experience.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Learn to set up and reconfigure bot settings directly within the ch
ms.topic: conceptual
ms.owner: angovil
ms.localizationpriority: high
ms.date: 12/11/2024
ms.date: 04/21/2026
---

# Bot configuration experience
Expand Down Expand Up @@ -73,162 +73,249 @@ In the app manifest (previously called Teams app manifest) file, update the `fet
For more information, see [app manifest schema](/microsoft-365/extensibility/schema/root-bots-configuration).

> [!div class="nextstepaction"]
> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Update+app+manifest&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fbot-configuration-experience%3Ftabs%3Dteams-bot-sdk1%252Cteams-bot-sdk2%252Cteams-bot-sdk3%23update-app-manifest&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fbot-configuration-experience.md&documentVersionIndependentId=415c2389-14be-5efd-9542-a58bf8a03900&platformId=7be118d5-e34d-24a2-73f8-81d8ec7c3cdf&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A)
> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Update+app+manifest&&author=%40vikasalmal&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fbot-configuration-experience%3Ftabs%3Dteams-bot-sdk1%252Cteams-bot-sdk2%252Cteams-bot-sdk3%23update-app-manifest&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fbot-configuration-experience.md&documentVersionIndependentId=415c2389-14be-5efd-9542-a58bf8a03900&platformId=7be118d5-e34d-24a2-73f8-81d8ec7c3cdf&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A)

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

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](../../task-modules-and-cards/what-are-task-modules.md).

* **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](../../messaging-extensions/how-to/action-commands/create-task-module.md#payload-activity-properties-when-a-dialog-is-invoked-from-a-group-chat).
* **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](../../messaging-extensions/how-to/action-commands/create-task-module.md#payload-activity-properties-when-a-dialog-is-invoked-from-a-group-chat).

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"` |
| `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](../../task-modules-and-cards/what-are-task-modules.md).

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](../../task-modules-and-cards/what-are-task-modules.md).
# [C#](#tab/teams-bot-sdk1)

# [C#](#tab/teams-bot-sdk1)
```csharp

[Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-configuration-app/csharp/Bot%20configuration/Bots/TeamsBot.cs#L78)
app.OnConfigFetch(async (context) =>
{
var card = new AdaptiveCard
{
Body = new List<CardElement>
{
new TextBlock("Configure your bot")
{
Weight = TextWeight.Bolder
}
},
Actions = new List<Action>
{
new SubmitAction
{
Title = "Submit"
}
}
};
var taskInfo = new TaskInfo
{
Title = "test card",
Width = new Union<int, Size>(600),
Height = new Union<int, Size>(500),
Card = new Attachment
{
ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
Content = card
}
};
return new ConfigTaskResponse(
new ContinueTask(taskInfo)
);
});
```

```csharp
protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
ConfigResponseBase response = adaptiveCardForContinue();
return Task.FromResult(response);
}
# [TypeScript](#tab/typescript1)

```typescript
app.on('config.fetch', async ({ activity }) => {
const card = new AdaptiveCard(
{
type: 'TextBlock',
text: 'Configure your bot',
weight: 'Bolder',
}
).withActions(
new SubmitAction().withTitle('Submit')
);
return {
config: {
type: 'continue',
value: {
card: cardAttachment('adaptive', card),
height: 500,
width: 600,
title: 'test card',
},
},
};
});
```

# [JavaScript](#tab/JS1)

[Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-configuration-app/nodejs/teamsBot.js#L52)

```javascript
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;
}
# [Python](#tab/Py1)
Copy link
Copy Markdown
Collaborator

@AjayJ12-MSFT AjayJ12-MSFT Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please update this code snippet

@app.on_config_open
async def handle_config_open(
ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
card = AdaptiveCard(
body=[
TextBlock(text="Configure your bot", weight="Bolder")
],
actions=[
SubmitAction(title="Submit")
]
)

return ConfigResponse(
    config=TaskModuleContinueResponse(
        value=CardTaskModuleTaskInfo(
            card=card_attachment(AdaptiveCardAttachment(content=card)),
            height=500,
            width=600,
            title="test card",
        )
    )
)


```python
@app.on_config_open
async def handle_config_open(
ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
card = AdaptiveCard(
body=[
TextBlock(text="Configure your bot", weight="Bolder")
],
actions=[
SubmitAction(title="Submit")
]
)

return ConfigResponse(
config=TaskModuleContinueResponse(
value=CardTaskModuleTaskInfo(
card=card_attachment(AdaptiveCardAttachment(content=card)),
height=500,
width=600,
title="test card",
)
)
)
```

---

* `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.
* `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.](../../messaging-extensions/how-to/add-authentication.md)

# [C#](#tab/teams-bot-sdk2)

[Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-configuration-app-auth/csharp/Bot%20configuration/Bots/TeamsBot.cs#L78)
# [C#](#tab/teams-bot-sdk2)

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

app.OnConfigFetch(async (context) =>
{
return new ConfigAuthResponse(
new ConfigAuth
{
SuggestedActions = new SuggestedActions
{
Actions = new List<CardAction>
{
new CardAction
{
Type = "openUrl",
Value = "https://example.com/auth",
Title = "Sign in to this app"
}
}
}
}
);
});

```

# [JavaScript](#tab/JS2)

[Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-configuration-app-auth/nodejs/teamsBot.js#L51)

```javascript
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;
}
# [TypeScript](#tab/typescript2)

```typescript
app.on('config.fetch', async ({ activity }) => {
return {
config: {
type: 'auth',
suggestedActions: {
actions: [
{
type: 'openUrl',
value: 'https://example.com/auth',
title: 'Sign in to this app',
},
],
},
},
};
});
```

# [Python](#tab/Py2)
Copy link
Copy Markdown
Collaborator

@AjayJ12-MSFT AjayJ12-MSFT Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update the code snippets

@app.on_config_open
async def handle_config_open(
ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
return ConfigResponse(
config=ConfigAuth(
suggested_actions=SuggestedActions(
to=[],
actions=[
CardAction(
type="openUrl",
value="https://example.com/auth",
title="Sign in to this app",
)
],
)
)
)


```python
@app.on_config_open
async def handle_config_open(
ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
return ConfigResponse(
config=ConfigAuth(
suggested_actions=SuggestedActions(
to=[],
actions=[
CardAction(
type="openUrl",
value="https://example.com/auth",
title="Sign in to this app",
)
],
)
)
)
```

---

* `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#](#tab/teams-bot-sdk3)

[Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-configuration-app-auth/csharp/Bot%20configuration/Bots/TeamsBot.cs#L102-L114)
# [C#](#tab/teams-bot-sdk3)

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

app.OnConfigSubmit(async (context) =>
{
return new ConfigTaskResponse(
new MessageTask("You have chosen to finish setting up bot")
);
});

```

# [TypeScript](#tab/TS3)

```typescript
app.on('config.submit', async ({ activity, send }) => {
return {
config: {
type: 'message',
value: 'You have chosen to finish setting up bot',
},
};
});
```

# [JavaScript](#tab/JS3)

[Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-configuration-app-auth/nodejs/teamsBot.js#L72-L83)

```javascript
async handleTeamsConfigSubmit(context, _configData) {
let response = {};
response = {
config: {
type: 'message',
value: 'You have chosen to finish setting up bot',
},
}
return response;
}
# [Python](#tab/Py3)

```python
@app.on_config_submit
async def handle_config_submit(
Copy link
Copy Markdown
Collaborator

@AjayJ12-MSFT AjayJ12-MSFT Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update the snippet

@app.on_config_submit
async def handle_config_submit(
ctx: ActivityContext[ConfigSubmitInvokeActivity]
) -> ConfigInvokeResponse:
return ConfigResponse(
config=TaskModuleMessageResponse(
value="You have chosen to finish setting up bot",
)
)

ctx: ActivityContext[ConfigSubmitInvokeActivity]
) -> ConfigInvokeResponse:
return ConfigResponse(
config=TaskModuleMessageResponse(
value="You have chosen to finish setting up bot",
)
)
```

---

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

Expand All @@ -239,7 +326,7 @@ When a user reconfigures the bot, the `fetchTask` property in the app manifest f
:::image type="content" source="../../assets/images/bots/reconfiguration-hover.gif" alt-text="Screenshot shows the configuration option for the bot in a Teams group chat.":::

> [!div class="nextstepaction"]
> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Configure+your+bot&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fbot-configuration-experience%3Ftabs%3Dteams-bot-sdk1%252Cteams-bot-sdk2%252Cteams-bot-sdk3%23configure-your-bot&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fbot-configuration-experience.md&documentVersionIndependentId=415c2389-14be-5efd-9542-a58bf8a03900&platformId=7be118d5-e34d-24a2-73f8-81d8ec7c3cdf&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A)
> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Configure+your+bot&&author=%40vikasalmal&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fbots%2Fhow-to%2Fbot-configuration-experience%3Ftabs%3Dteams-bot-sdk1%252Cteams-bot-sdk2%252Cteams-bot-sdk3%23configure-your-bot&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fbots%2Fhow-to%2Fbot-configuration-experience.md&documentVersionIndependentId=415c2389-14be-5efd-9542-a58bf8a03900&platformId=7be118d5-e34d-24a2-73f8-81d8ec7c3cdf&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A)

## Best practices

Expand Down