| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| platform | Get Teams Context | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/bots/how-to/get-teams-context.md | A bot can access additional context data about a team or chat where it's install ## Fetch the roster or user profile -Your bot can query for the list of members and their basic user profiles, including Teams user IDs and Microsoft Azure Active Directory (Azure AD) information, such as name and objectId. You can use this information to correlate user identities. For example, to check whether a user logged into a tab through Azure AD credentials, is a member of the team. For get conversation members, minimum or maximum page size depends on the implementation. Page size less than 50, are treated as 50, and greater than 500, are capped at 500. Even if you use the non-paged version, it's unreliable in large teams and must not be used. For more information, see [changes to Teams Bot APIs for fetching team or chat members](~/resources/team-chat-member-api-changes.md). +Your bot can query for the list of members and their basic user profiles, including Teams user IDs and Microsoft Azure Active Directory (Azure AD) information, such as name and objectId. You can use this information to correlate user identities. For example, to check whether a user logged into a tab through Azure AD credentials is a member of the team. For get conversation members, minimum or maximum page size depends on the implementation. Page size less than 50, are treated as 50, and greater than 500, are capped at 500. Even if you use the non-paged version, it's unreliable in large teams and must not be used. For more information, see [changes to Teams Bot APIs for fetching team or chat members](~/resources/team-chat-member-api-changes.md). ++> [!NOTE] +> +> * Pagination is available in a team and a channel. +> * Pagination isn't supported in chats. For chats, the entire roster is always returned. The following sample code uses the paged endpoint for fetching the roster: |
| platform | Messaging Extensions Common | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/includes/messaging-extensions/messaging-extensions-common.md | A message extension is a cloud-hosted service that listens to user requests and responds with structured data, such as a [card](~/task-modules-and-cards/what-are-cards.md). You integrate your service with Microsoft Teams via Bot Framework `Activity` objects. Our .NET and Node.js extensions for the Bot Builder SDK can help you add message extension functionality to your app. ### Register in the Bot Framework If you havenΓÇÖt done so already, you must first register a bot with the Microsoft Bot Framework. The Microsoft app ID and callback endpoints for your bot, as defined there, will be used in your message extension to receive and respond to user requests. Remember to enable the Microsoft Teams channel for your bot. -Record your bot app ID and app password, you'll need to supply the app ID in your app manifest. +Take note of your bot app ID and app password, you'll need to provide the app ID in your app manifest. ### Update your app manifest -As with bots and tabs, you update the [manifest](~/resources/schem#composeextensions) of your app to include the message extension properties. These properties govern how your message extension appears and behaves in the Microsoft Teams client. Message extensions are supported beginning with v1.0 of the manifest. +As with bots and tabs, you update the [manifest](~/resources/schem#composeextensions) of your app to include the message extension properties. These properties govern how your message extension appears and behaves in the Microsoft Teams client. Message extensions are supported beginning with manifest v1.0. #### Declare your message extension The extension definition is an object that has the following structure: Your message extension should declare one command, which appears when the user selects your app from the **More options** (**⋯**) button in the compose box. - In the app manifest, your command item is an object with the following structure: In the app manifest, your command item is an object with the following structure | `id` | Unique ID that you assign to this command. The user request will include this ID. | Yes | 1.0 | | `title` | Command name. This value appears in the UI. | Yes | 1.0 | | `description` | Help text indicating what this command does. This value appears in the UI. | Yes | 1.0 |-| `type` | Set the type of command. Possible values include `query` and `action`. If not, present the default value is set to `query`. | No | 1.4 | +| `type` | Set the type of command. Possible values include `query` and `action`. If not present, the default value is set to `query`. | No | 1.4 | | `initialRun` | Optional parameter, used with `query` commands. If set to **true**, indicates this command should be executed as soon as the user chooses this command in the UI. | No | 1.0 |-| `fetchTask` | Optional parameter, used with `action` commands. Set to **true** to fetch the adaptive card or web url to display within the [task module](~/task-modules-and-cards/what-are-task-modules.md). This is used when the input to the `action` command is dynamic as opposed to a static set of parameters. Note that if set to **true** the static parameter list for the command is ignored. | No | 1.4 | +| `fetchTask` | Optional parameter, used with `action` commands. Set to **true** to fetch the adaptive card or web url to display within the [task module](~/task-modules-and-cards/what-are-task-modules.md). This is used when the input to the `action` command is dynamic as opposed to a static set of parameters. Note that if set to **true**, the static parameter list for the command is ignored. | No | 1.4 | | `parameters` | Static list of parameters for the command. | Yes | 1.0 | | `parameter.name` | The name of the parameter. This is sent to your service in the user request. | Yes | 1.0 |-| `parameter.description` | Describes this parameterΓÇÖs purposes or example of the value that should be provided. This value appears in the UI. | Yes | 1.0 | +| `parameter.description` | Describes this parameterΓÇÖs purposes and example of the value that should be provided. This value appears in the UI. | Yes | 1.0 | | `parameter.title` | Short user-friendly parameter title or label. | Yes | 1.0 | | `parameter.inputType` | Set to the type of input required. Possible values include `text`, `textarea`, `number`, `date`, `time`, `toggle`. Default is set to `text`. | No | 1.4 | | `context` | Optional array of values that defines the context the message action is available in. Possible values are `message`, `compose`, or `commandBox`. Default is `["compose", "commandBox"]`. | No | 1.5 | |
| platform | V3 To V4 Pointer Me | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/includes/v3-to-v4-pointer-me.md | > [!Important] -> The articles in this section are based on the v3 Bot Framework SDK. If you're looking for current documentation (version 4.6 or later version of the SDK) see the [Task-oriented interactions with Message Extensions](~/messaging-extensions/what-are-messaging-extensions.md) section. +> The articles in this section are based on the v3 Bot Framework SDK. If you're looking for current documentation (version 4.6 or later version of the SDK), see the [Task-oriented interactions with Message Extensions](~/messaging-extensions/what-are-messaging-extensions.md) section. |
| platform | Create Extensions | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/resources/messaging-extension-v3/create-extensions.md | Title: Initiate actions with message extensions -description: In this module, learn create Action-based message extensions to allow users to trigger external services +description: In this module, learn create Action-based message extensions to allow users to trigger external services. ms.localizationpriority: medium - [!include[Common content for creating extensions](~/includes/messaging-extensions/messaging-extensions-common.md)] ## Action type message extensions -To initiate actions from a message extension, set the `type` parameter to `action`. Below is an example of a manifest with a search and a create command. A single message extension can have up to 10 different commands and include multiple search and action-based commands. +To initiate actions from a message extension, set the `type` parameter to `action`. Below is an example of a manifest with a search and a create command. A single message extension can have up to 10 different commands and include multiple search-based and action-based commands. > [!NOTE] >`justInTimeInstall` functions when you upload an app to the app catalog but fails when you sideload an app. To initiate actions from a message extension, set the `type` parameter to `actio ### Initiate actions from messages -You can initiate actions from the compose message area and also use your message extension to initiate an action from a message, which allows you to send the message contents to your bot for processing. Optionally, you can reply to that message with a response using the method described in [Responding to submit](#responding-to-submit). The response will be inserted as a reply to the message that your users can edit before submitting. Your users can access message extension from the overflow `...` menu and then selecting `Take action` as in the following image: +You can initiate actions from the compose message area and also from a message using your message extension, which allows you to send the message contents to your bot for processing. You can optionally respond to that message using the method described in [Responding to submit](#responding-to-submit). The response is included as a reply to the message, which users can edit before submitting. - +Users can access message extension from **Take action** option of the overflow `...` menu, as shown in the following image: + To enable your message extension to work from a message, add the `context` parameter to your message extension's `commands` object in your app manifest as in the following example. Valid strings for the `context` array are `"message"`, `"commandBox"`, and `"compose"`. The default value is `["compose", "commandBox"]`. See the [define commands](#define-commands) section for complete details on the `context` parameter: To enable your message extension to work from a message, add the `context` param ``` -Below is an example of the `value` object containing the message details that will be sent as part of the `composeExtension` request be sent to your bot. +Below is an example of the `value` object containing the message details that will be sent as part of the `composeExtension` request to your bot. ```json { Below is an example of the `value` object containing the message details that wi You can test your message extension by uploading your app. For more information, see [Uploading your app in a team](~/concepts/deploy-and-publish/apps-upload.md). -To open your message extension, go to any of your chats or channels. Choose the **More options** (**⋯**) button in the compose box, and choose your message extension. +To open your message extension, go to any of your chats or channels. Select the **More options** (**⋯**) button in the compose box and choose your message extension. ## Collecting input from users -There are three ways to collect information from an end user in Teams. +There are three ways to collect information from a user in Teams. ### Static parameter list -In this method, all you need to do is define a static list of parameters in the manifest as shown above in the "Create To Do" command. To use this method ensure `fetchTask` is set to `false` and that you define your parameters in the manifest. +In this method, all you need to do is define a static list of parameters in the manifest as shown above in the "Create To Do" command. To use this method, ensure `fetchTask` is set to `false` and that you define your parameters in the manifest. -When a user chooses a command with static parameters, Teams will generate a form in a Task Module with the defined parameters in the manifest. On hitting Submit, a `composeExtension/submitAction` is sent to the bot. For more information on the expected set of responses, see [Responding to submit](#responding-to-submit). +When a user chooses a command with static parameters, Teams will generate a form in a task module with the defined parameters in the manifest. On hitting Submit, a `composeExtension/submitAction` is sent to the bot. For more information on the expected set of responses, see [Responding to submit](#responding-to-submit). ### Dynamic input using an adaptive card -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 will be ignored. +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 will be ignored. In this method, your service receives a `composeExtension/fetchTask` event and responds with an adaptive card based [task module response](~/task-modules-and-cards/task-modules/invoking-task-modules.md#the-taskinfo-object). Following is a sample response with an adaptive card: The bot can also respond with an auth/config response if the user needs to authe In this method, your service can show an `<iframe>` based widget to show any custom UI and collect user input. For this approach, set the `fetchTask` parameter to `true` in the manifest. -Just like in the adaptive card flow your service sends a `fetchTask` event and responds with a URL based [task module response](~/task-modules-and-cards/task-modules/invoking-task-modules.md#the-taskinfo-object). Following is a sample response with an Adaptive card: +Just like in the adaptive card flow, your service sends a `fetchTask` event and responds with a URL based [task module response](~/task-modules-and-cards/task-modules/invoking-task-modules.md#the-taskinfo-object). Following is a sample response with an Adaptive card: ```json { Just like in the adaptive card flow your service sends a `fetchTask` event and r If your app contains a conversation bot, ensure it's installed in the conversation before loading your task module to get more context for your task module. For example, you may need to fetch the roster to populate a people picker control, or the list of channels in a team. -To facilitate this flow, when your message extension first receives the `composeExtension/fetchTask` invoke check to see if your bot is installed in the current context. You can get this, by attempting the get roster call. For example, if your bot isn't installed, you return an Adaptive Card with an action that requests the user to install your bot. The user needs to have permission to install apps in that location. If they canΓÇÖt install, the message prompts to contact the administrator. +To facilitate this flow, when your message extension first receives the `composeExtension/fetchTask` invoke, check to see if your bot is installed in the current context. You can get this, by attempting the get roster call. For example, if your bot isn't installed, you return an Adaptive Card with an action that requests the user to install your bot. The user needs to have permission to install apps in that location. If they canΓÇÖt install, the message prompts to contact the administrator. Here's an example of the response: Here's an example of the response: } ``` -Once the user completes the installation, your bot will receive another invoke message with `name = composeExtension/submitAction`, and `value.data.msteams.justInTimeInstall = true`. +Once the user completes the installation, your bot will receive another invoke message with `name = composeExtension/submitAction` and `value.data.msteams.justInTimeInstall = true`. Here's an example of the invoke: Once a user completes entering their input, bot will receive a `composeExtension These are the different expected responses to a `submitAction`. -### Task Module response +### Task module response -Task Module response is used when your extension needs to chain dialogs together to get more information. The response is exactly the same as `fetchTask` mentioned earlier. +Task module response is used when your extension needs to chain dialogs together to get more information. The response is same as `fetchTask` mentioned earlier. ### Compose extension auth/config response Respond to the submit action by inserting a message with an Adaptive Card into t 1. After submitting the configuration task module, the app uses the information provided in the task module to craft an adaptive card and sends it as a `botMessagePreview` response to the client. 1. The user can then preview the adaptive card message before the bot inserts it into the channel. If the bot isn't already a member of the channel, clicking `Send` will add the bot. 1. Interacting with the adaptive card will change the message before sending it.-1. Once the user selects `Send` the bot will post the message to the channel. +1. Once the user selects `Send`, the bot will post the message to the channel. To enable this flow your task module should respond as in the example below, which will present the preview message to the user. > [!NOTE]-> The `activityPreview` must contain a `message` activity with exactly 1 adaptive card attachment. +> The `activityPreview` must contain a `message` activity with exactly one adaptive card attachment. ```json { |
| platform | Auth Flow Tab | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/tabs/how-to/authentication/auth-flow-tab.md | Title: Enable authentication using third-party OAuth provider -description: Learn about Teams authentication flow in tabs using third party OAuth provider with Azure AD configuration and code samples. +description: Learn about Teams authentication flow in tabs using third-party OAuth provider with Azure AD configuration and code samples. ms.localizationpriority: high # Enable authentication using third-party OAuth provider -You can enable authentication in your tab app using third party OAuth Identity Providers (IdP). In this method, the app user identity is validated and granted access by an OAuth IdP, such as Azure AD, Google, Facebook, GitHub, or any other provider. You'll need to configure a trust relationship with the IdP, and your app users should also be registered with it. +You can enable authentication in your tab app using third-party OAuth Identity Providers (IdP). In this method, the app user identity is validated and granted access by an OAuth IdP, such as Azure AD, Google, Facebook, GitHub, or any other provider. You'll need to configure a trust relationship with the IdP, and your app users should also be registered with it. > [!NOTE]-> For authentication to work for your tab on mobile clients, you need to ensure that you're using at least 1.4.1 version of the Microsoft Teams JavaScript SDK. -> Teams SDK launches separate window for authentication flow. Set the `SameSite` attribute to **Lax**. Teams desktop client or older versions of Chrome or Safari do not support `SameSite`=None. +> +> *For authentication to work for your tab on mobile clients, you need to ensure that you're using at least 1.4.1 version of the Microsoft Teams JavaScript SDK. +> +> *Teams SDK launches separate window for authentication flow. Set the `SameSite` attribute to **Lax**. Teams desktop client or older versions of Chrome or Safari do not support `SameSite`=None. [!INCLUDE [sdk-include](~/includes/sdk-include.md)] OAuth 2.0 is an open standard for authentication and authorization used by Micro For example, the authentication flow for tabs and bots using Node and the [OAuth 2.0 implicit grant type](https://oauth.net/2/grant-types/implicit/), see [initiate authentication flow for tabs](~/tabs/how-to/authentication/auth-tab-aad.md#initiate-authentication-flow). -This section uses Azure AD as an example of a third party OAuth provider for enabling authentication in a tab app. +This section uses Azure AD as an example of a third-party OAuth provider for enabling authentication in a tab app. > [!NOTE]+> > Before showing a **Login** button to the user and calling the `authentication.authenticate` API in response to selecting the button, you must wait for the SDK initialization to complete. You can chain a `.then()` handler or `await` for the `app.initialize()` function to complete.  This section uses Azure AD as an example of a third party OAuth provider for ena Similar to other application auth flows in Teams, the start page must be on a domain that is in its `validDomains` list, and on the same domain as the post sign in redirect page. > [!NOTE]+ > > The OAuth 2.0 implicit grant flow calls for a `state` parameter in the authentication request, which contains unique session data to prevent a [cross-site request forgery attack](https://en.wikipedia.org/wiki/Cross-site_request_forgery). The examples use a randomly-generated GUID for the `state` data. 5. On the provider's site, the user sign in and grants access to the tab. Similar to other application auth flows in Teams, the start page must be on a do 9. The tab either displays configuration UI, refreshes, or reloads the tabs content, depending on where the user started from. > [!NOTE]+> > If the application supports SAML SSO, then tab SSO generated JWT token cannot be used as it isn't supported. ## Treat tab context as hints Sample code showing the tab authentication process: | **Sample name** | **Description** | **C#** | **Node.js** | |--|--|-||-| Teams tab authentication | Authentication process for tabs using Azure AD. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-complete-sample/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-complete-sample/nodejs) | +| App complete authentication | The sample demos authentication in a bot, tab, and messaging extension with Single sign-on (SSO) and in Facebook using a username and password | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-complete-auth/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-complete-auth/nodejs) | ## See also |