From 6435931eeed4c1c828bea3e19499e8a248efe65c Mon Sep 17 00:00:00 2001 From: v-nikitach Date: Tue, 14 Apr 2026 16:54:12 +0530 Subject: [PATCH 1/8] Update invoking-task-modules.md --- .../task-modules/invoking-task-modules.md | 462 ++++++++++++------ 1 file changed, 309 insertions(+), 153 deletions(-) diff --git a/msteams-platform/task-modules-and-cards/task-modules/invoking-task-modules.md b/msteams-platform/task-modules-and-cards/task-modules/invoking-task-modules.md index 1dc5f61e576..7d5fd7cd2c0 100644 --- a/msteams-platform/task-modules-and-cards/task-modules/invoking-task-modules.md +++ b/msteams-platform/task-modules-and-cards/task-modules/invoking-task-modules.md @@ -1,227 +1,383 @@ --- -title: Invoke Dialogs from Tab, Bot, or Link -description: Learn about invoking and dismissing dialogs (task modules), the dialog info object, dialog sizing, and dialog deep link syntax using code samples. +title: Invoke and dismiss dialogs +description: Learn how to invoke and dismiss dialogs using Adaptive Card actions in the Teams SDK, including the TaskInfo object, dialog sizing, and code samples. ms.topic: conceptual ms.localizationpriority: medium -ms.date: 01/29/2023 +ms.date: 04/13/2026 --- # Invoke and dismiss dialogs -Dialogs (referred as task modules in TeamsJS v1.x) can be invoked from tabs, bots, or deep links. The response can be either in HTML, JavaScript, or as an Adaptive Card. There's a numerous flexibilities in terms of how dialogs are invoked and how to deal with the response of the user's interaction. The following table summarizes how this works. +Dialogs (formerly known as task modules) provide a way to open modal windows within the Microsoft Teams interface. In the Teams SDK, dialogs are invoked from Adaptive Card actions using the `TaskFetchAction` and handled through `dialog.open` and `dialog.submit` events on the `App` class. The dialog content can be an Adaptive Card or a URL-based webpage. > [!NOTE] -> The `task` capability is replaced with `dialog` capability in both HTML-based dialogs (starting with TeamsJS v.2.0.0) and Adaptive Card-based dialogs (starting with TeamsJS v.2.8.0). For more information, see [dialog](./../../m365-apps/teamsjs-support-m365.md#dialog). +> In the Teams SDK (Teams AI Library), dialogs must be triggered via Adaptive Card actions and cannot be invoked directly from client-side tab JavaScript or deep links. For migration guidance, see [Migrate from BotBuilder](/microsoftteams/platform/teams-sdk/migrations/botbuilder/overview). -| Invoked using | Dialog with HTML or JavaScript | Dialog with Adaptive Card | +The following table summarizes how dialogs work in the Teams SDK: + +| Step | Dialog with Adaptive Card | Dialog with webpage URL | | --- | --- | --- | -| JavaScript in a tab | 1. Use the Teams client library function `dialog.url.open()` with optional `submitHandler(err, result)` and `messageFromChildHandler(postMessageChannel)` callback functions.

2. In the dialog code, when the user has performed the actions, call the TeamsJS library function `dialog.url.submit()` with (optionally) a `result` object as a parameter. If a `submitHandler` callback was specified in `dialog.open()`, Teams calls it with `result` as a parameter. If there was an error when invoking `dialog.open()`, the `submitHandler` function is called with an `err` string instead. | 1. Call the Teams client library function `dialog.adaptiveCard.open()` with a [AdaptiveCardDialogInfo object](#adaptivecarddialoginfo-object) specifying the JSON for the Adaptive Card (`AdaptiveCardDialogInfo.card`) to show in the modal dialog.

2. If a `submitHandler` callback was specified in `dialog.adaptiveCard.open()`, Teams calls it with an `err` string if there was an error when invoking the dialog or if the user closes the modal dialog.

3. If the user presses an `Action.Submit` button then its `data` object is returned as the value of `result`. | -| Bot card button | 1. Bot card buttons, depending on the type of button, can invoke dialogs from either a deep link URL, or by sending a `task/fetch` message.

2. If the button's action `type` is [`task/fetch`](task-modules-bots.md#invoke-a-dialog-using-taskfetch) or `Action.Submit` button type for Adaptive Cards, a `task/fetch invoke` event that is an HTTP POST is sent to the bot. The bot responds to the POST with HTTP 200 and the response body containing a wrapper around the [DialogInfo object](#dialoginfo-object). Teams displays the dialog.

3. After the user has performed the actions, call the `Actions.Submit` Adaptive Card action with the result. The bot receives a `task/submit invoke` message that contains the result.

4. You have three different ways to respond to the `task/submit` message: do nothing (if the task completed successfully), display a message to the user in the dialog, or invoke another dialog. For more information, see [detailed discussion on `task/submit`](task-modules-bots.md#responds-to-the-tasksubmit-messages). |

| -| Deep link URL*

*\*Deprecated; supported for backwards compability*| 1. Teams invokes the dialog that is the URL that appears inside the ` - - - + return Task.FromResult(new Response(new MessageTask("Unknown dialog type"))); +} ``` -The following code provides an example of the CSS: - -```css -#embed-container iframe { - position: absolute; - top: 0; - left: 0; - width: 95%; - height: 95%; - padding-left: 20px; - padding-right: 20px; - padding-top: 10px; - padding-bottom: 10px; - border-style: none; -} +# [TypeScript](#tab/typescript) + +```typescript +import { cardAttachment } from '@microsoft/teams.api'; +import { App } from '@microsoft/teams.apps'; +import { AdaptiveCard, TextInput, SubmitAction } from '@microsoft/teams.cards'; + +app.on('dialog.open', async ({ activity }) => { + const dialogType = activity.value.data?.opendialogtype; + + if (dialogType === 'simple_form') { + const dialogCard = new AdaptiveCard( + { + type: 'TextBlock', + text: 'This is a simple form', + size: 'Large', + weight: 'Bolder', + }, + new TextInput() + .withLabel('Name') + .withIsRequired() + .withId('name') + .withPlaceholder('Enter your name') + ).withActions( + new SubmitAction().withTitle('Submit').withData({ submissiondialogtype: 'simple_form' }) + ); + + return { + task: { + type: 'continue', + value: { + title: 'Simple Form Dialog', + card: cardAttachment('adaptive', dialogCard), + }, + }, + }; + } +}); ``` -### Example 2: PowerApp +# [Python](#tab/python) -You can use the same approach to embed a PowerApp. As the height or width of any individual PowerApp is customizable, you can adjust the height, and width to achieve the desired presentation. +```python +from microsoft_teams.api import TaskInfo, Attachment, ContentType +from microsoft_teams.cards import AdaptiveCard, TextBlock, TextInput, SubmitAction -:::image type="content" source="../../assets/images/task-module/powerapp-example.png" alt-text="powerapp"::: +@app.on_task_fetch +async def handle_task_fetch(ctx): + dialog_type = ctx.activity.value.data.get("OpenDialogType") -The following code provides an example of the HTML for PowerApp: + if dialog_type == "simple_form": + card = AdaptiveCard( + body=[ + TextBlock(text="This is a simple form", size="Large", weight="Bolder"), + TextInput(id="name", label="Name", placeholder="Enter your name", is_required=True) + ] + ).with_actions([ + SubmitAction(title="Submit", data={"submissiondialogtype": "simple_form"}) + ]) -```html - + return {"task": {"type": "continue", "value": {"title": "Simple Form Dialog", "card": card}}} ``` -The following code provides an example of the CSS: - -```css -#embed-container iframe { - position: absolute; - top: 0; - left: 0; - width: 94%; - height: 95%; - padding-left: 20px; - padding-right: 20px; - padding-top: 10px; - padding-bottom: 10px; - border-style: none; -} -``` +--- -The next section provides details on invoking your card using Adaptive Card or Adaptive Card bot card attachment. +## Handle the dialog submission -## Adaptive Card or Adaptive Card bot card attachment +When a user presses `Action.Submit` in a dialog, Teams sends a `dialog.submit` event to your app. You can respond by completing the task, showing a message, or opening another dialog. -Depending on how you're invoking your card, you'll need to use either an Adaptive Card or an Adaptive Card bot card attachment (an Adaptive Card wrapped in an `attachment` object). +# [C#](#tab/csharp) -If you're invoking from a tab, use an Adaptive Card: +```csharp +using System.Text.Json; +using Microsoft.Teams.Api.TaskModules; +using Microsoft.Teams.Apps; +using Microsoft.Teams.Apps.Activities.Invokes; +using Microsoft.Teams.Apps.Annotations; +using Microsoft.Teams.Common.Logging; -```json +[TaskSubmit] +public async Task OnTaskSubmit([Context] Tasks.SubmitActivity activity, [Context] IContext.Client client, [Context] ILogger log) { - "type": "AdaptiveCard", - "body": [ - { - "type": "TextBlock", - "text": "Here is a guitar:" - }, - { - "type": "Image", - "url": "https://adaptivecards.microsoft.com/images/guitar1.jpeg", - "size": "Medium" - } - ], - "version": "1.0" + var data = activity.Value?.Data as JsonElement?; + if (data == null) + { + return new Response(new MessageTask("No data found in the activity value")); + } + + var submissionType = data.Value.TryGetProperty("submissiondialogtype", out var typeObj) && typeObj.ValueKind == JsonValueKind.String + ? typeObj.ToString() + : null; + + switch (submissionType) + { + case "simple_form": + var name = data.Value.TryGetProperty("name", out var nameVal) ? nameVal.GetString() : "Unknown"; + await client.Send($"Hi {name}, thanks for submitting the form!"); + return new Response(new MessageTask("Form was submitted")); + default: + return new Response(new MessageTask("Unknown submission type")); + } } ``` -If you're invoking from a bot, use an Adaptive Card bot card attachment: +# [TypeScript](#tab/typescript) + +```typescript +import { App } from '@microsoft/teams.apps'; + +app.on('dialog.submit', async ({ activity, send }) => { + const dialogType = activity.value.data?.submissiondialogtype; + + if (dialogType === 'simple_form') { + const name = activity.value.data.name; + await send(`Hi ${name}, thanks for submitting the form!`); + return { + task: { + type: 'message', + value: 'Form was submitted', + }, + }; + } +}); +``` -```json -{ - "contentType": "application/vnd.microsoft.card.adaptive", - "content": { - "type": "AdaptiveCard", - "body": [ - { - "type": "TextBlock", - "text": "Here is a guitar:" - }, - { - "type": "Image", - "url": "https://adaptivecards.microsoft.com/images/guitar1.jpeg", - "size": "Medium" - } - ], - "version": "1.0" - } -} +# [Python](#tab/python) + +```python +@app.on_task_submit +async def handle_task_submit(ctx): + submission_type = ctx.activity.value.data.get("submissiondialogtype") + + if submission_type == "simple_form": + name = ctx.activity.value.data.get("name", "Unknown") + await ctx.send(f"Hi {name}, thanks for submitting the form!") + return {"task": {"type": "message", "value": "Form was submitted"}} ``` -The next section provides details on dialog accessibility. +--- ## Keyboard and accessibility guidelines -With HTML or JavaScript-based dialogs, you must ensure that users can interact with your dialog with a keyboard. Screen reader programs also depend on the ability to navigate using the keyboard. Following are the important considerations: +For URL-based dialogs that load HTML content, ensure keyboard accessibility: -* Using the [tabindex attribute](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/tabindex) in your HTML tags to control which elements can be focused. Also, use tabindex attribute to identify where it participates in sequential keyboard navigation usually with the Tab and Shift-Tab keys. -* Handling the Esc key in the JavaScript for your dialog. The following code provides an example of how to handle the Esc key: - - ```javascript - // Handle the Esc key - document.onkeyup = function(event) { - if ((event.key === 27) || (event.key === "Escape")) { - microsoftTeams.submitTask(null); // this will return an err object to the completionHandler() - } - } - ``` +* Use the [tabindex attribute](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/tabindex) in your HTML tags to control which elements can be focused and to define sequential keyboard navigation with the Tab and Shift-Tab keys. +* Handle the Esc key appropriately in the JavaScript for your dialog page. Microsoft Teams ensures that keyboard navigation works properly from the dialog header into your HTML and vice-versa. ## Code sample -|Sample name | Description | .NET | Node.js | Manifest| +|Sample name | Description | .NET | Node.js | Python | |----------------|-----------------|--------------|----------------|----------------| -|Dialog sample bots-V4 | This sample app demonstrate how to use Dialogs (referred as task modules in TeamsJS v1.x) using Bot Framework v4. |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-task-module/csharp)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-task-module/nodejs)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-task-module/csharp/demo-manifest/bot-task-module.zip) +|Dialog sample - Teams SDK | This sample app demonstrates how to use dialogs with the Teams SDK. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-task-modules/dotnet/bot-task-modules)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-task-modules/nodejs/bot-task-modules) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-task-modules/python/bot-task-modules) | ## Next step @@ -231,7 +387,7 @@ Microsoft Teams ensures that keyboard navigation works properly from the dialog ## See also * [Cards and dialogs](../cards-and-task-modules.md) -* [Request device permissions](~/concepts/device-capabilities/native-device-permissions.md) -* [Integrate media capabilities](~/concepts/device-capabilities/media-capabilities.md) -* [Integrate QR or barcode scanner capability in Teams](~/concepts/device-capabilities/qr-barcode-scanner-capability.md) -* [Integrate location capabilities in Teams](~/concepts/device-capabilities/location-capability.md) +* [Teams SDK overview](/microsoftteams/platform/teams-sdk/) +* [Dialogs in the Teams SDK](/microsoftteams/platform/teams-sdk/in-depth-guides/dialogs/overview) +* [Adaptive Cards in the Teams SDK](/microsoftteams/platform/teams-sdk/in-depth-guides/adaptive-cards/overview) +* [Migrate from BotBuilder](/microsoftteams/platform/teams-sdk/migrations/botbuilder/overview) From 6b3073f3d7d7f65af2565dd6105aee3a2e8e4e9a Mon Sep 17 00:00:00 2001 From: v-nikitach Date: Tue, 14 Apr 2026 17:07:56 +0530 Subject: [PATCH 2/8] resolved warnings --- .../concepts/build-and-test/deep-link-application.md | 2 +- msteams-platform/get-started/glossary.md | 2 +- .../resources/messaging-extension-v3/create-extensions.md | 4 ++-- .../task-modules/task-modules-bots.md | 4 ++-- .../task-modules/task-modules-tabs.md | 2 +- .../task-modules-and-cards/what-are-task-modules.md | 6 +++--- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/msteams-platform/concepts/build-and-test/deep-link-application.md b/msteams-platform/concepts/build-and-test/deep-link-application.md index cc9f5d3ebc7..2bbbbc8e1f9 100644 --- a/msteams-platform/concepts/build-and-test/deep-link-application.md +++ b/msteams-platform/concepts/build-and-test/deep-link-application.md @@ -376,7 +376,7 @@ A dialog deep link is a serialization of the `TaskInfo` object with two other de --- -For the data types and allowable values for ``, ``, ``, ``, and ``, see [TaskInfo object](~/task-modules-and-cards/task-modules/invoking-task-modules.md#dialoginfo-object). +For the data types and allowable values for ``, ``, ``, ``, and ``, see [TaskInfo object](~/task-modules-and-cards/task-modules/invoking-task-modules.md#taskinfo-object). > [!TIP] > Encode the deep link URL when using the `card` parameter, for example, JavaScript [`encodeURI()` function](https://www.w3schools.com/jsref/jsref_encodeURI.asp). diff --git a/msteams-platform/get-started/glossary.md b/msteams-platform/get-started/glossary.md index 872bd4ac4cb..db070a5d96f 100644 --- a/msteams-platform/get-started/glossary.md +++ b/msteams-platform/get-started/glossary.md @@ -260,7 +260,7 @@ Common terms and definitions used in Microsoft Teams developer documentation. | [Tab](../tabs/what-are-tabs.md) | Tabs are client-aware webpages embedded in Microsoft Teams, Outlook, and Microsoft 365 that point to domains declared in app manifest. You can add it as part of a channel inside a team, group chat, or personal app for an individual user. | | [Tab chat](../tabs/how-to/conversational-tabs.md) | A type of tab that lets a user have a focused conversation experience in dynamic tabs. | | [Task modules](../task-modules-and-cards/what-are-task-modules.md) (referred as dialogs in TeamsJS v2.x)| A feature of Teams app to create modal pop-up for completing tasks, displaying videos, or dashboard.
**See also**: [Adaptive Card](#a), [Dialogs](#d) | -| [Task info](../task-modules-and-cards/task-modules/invoking-task-modules.md#dialoginfo-object) | The `TaskInfo` object contains the metadata for a dialogs (referred as task modules in TeamsJS v.1.0).| +| [Task info](../task-modules-and-cards/task-modules/invoking-task-modules.md#taskinfo-object) | The `TaskInfo` object contains the metadata for a dialog (referred as task modules in TeamsJS v.1.0).| | [Thread discussion](../tabs/design/tabs.md#thread-discussion) | A conversation posted on a channel or chat between users.
**See also** [Conversation](#c); [Channel](#c) | | [Teams](../overview.md) | Microsoft Teams is the ultimate message app for your organization. It's a workspace for real-time collaboration and communication, meetings, file and app sharing. | | [Teams SDK](/microsoftteams/platform/teams-ai-library/welcome) (formerly known as Teams AI library) | It provides a simplified SDK, support for Model Context Protocol (MCP), Agent-to-Agent communication (A2A), and streamlined tools to enable developers to build intelligent agents for Teams.
**See also**: [Custom engine agent](#c) | diff --git a/msteams-platform/resources/messaging-extension-v3/create-extensions.md b/msteams-platform/resources/messaging-extension-v3/create-extensions.md index c7377f0dfcb..41a6bc522ae 100644 --- a/msteams-platform/resources/messaging-extension-v3/create-extensions.md +++ b/msteams-platform/resources/messaging-extension-v3/create-extensions.md @@ -241,7 +241,7 @@ When a user chooses a command with static parameters, Teams generates a form in In this method, your service can define a custom Adaptive Card to collect the user input. For this approach, set the `fetchTask` parameter to `true` in the manifest. If you set `fetchTask` to `true`, any static parameters defined for the command are ignored. -In this method, your service receives a `composeExtensions/fetchTask` event and responds with an Adaptive Card based [task module response](~/task-modules-and-cards/task-modules/invoking-task-modules.md#dialoginfo-object). Following is a sample response with an Adaptive Card: +In this method, your service receives a `composeExtensions/fetchTask` event and responds with an Adaptive Card based [task module response](~/task-modules-and-cards/task-modules/invoking-task-modules.md#taskinfo-object). Following is a sample response with an Adaptive Card: ```json { @@ -292,7 +292,7 @@ The bot can also respond with an auth/config response if the user needs to authe In this method, your service can show an `