| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| platform | Send Proactive Messages | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/bots/how-to/conversations/send-proactive-messages.md | A good welcome message can include the following: ### Notification messages -To send notifications using proactive messaging, ensure your users have a clear path to take common actions based on your notification. Ensure users have a clear understanding of why they've received a notification. Good notification messages generally include the following items: +To send notifications using proactive messaging, ensure your users have a clear path to take common actions based on your notification. If user actions are required in a tab app, use activity feed notifications instead of a bot. Ensure users have a clear understanding of why they've received a notification. Good notification messages generally include the following items: * What happened? A clear indication of what happened to cause the notification. |
| platform | Map Use Cases | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/concepts/design/map-use-cases.md | Title: Map your use cases to Teams app features and capabilities -description: Identify how your app's use cases can work within the Teams experience, app features and capabilities; map common use cases with capabilities. +description: Identify how your app's use cases can work within the Teams experience, app features, and capabilities; map common use cases with capabilities. ms.localizationpriority: high Send asynchronous notifications and alerts to your users in Teams. | **If you want to...** | **Try ...** | | | |-| Send proactive messages to groups, channels, or individual users. | Conversational bots | +| Send proactive notifications to inform users about news, events, requests, and reminders that require usersΓÇÖ immediate attention or specific actions in the activity feed. | Microsoft Graph API (`sendActivityNotification`) | +| Send interactive messages to groups, channels, or individual users. | Conversational bots | | Permit a channel to subscribe to receive messages. A connector lets users tailor the subscription with a configuration page. | Connectors and incoming webhooks | </details> Let's look at how Teams capabilities enable different features for your Teams ap :::row::: :::image type="content" source="~/assets/images/overview/flowchart-tab.png" alt-text="Microsoft Teams app capabilities for tab." link="~/tabs/what-are-tabs.md" border="false"::: :::row-end:::- + :::row::: :::image type="content" source="~/assets/images/overview/flowchart-bot.png" alt-text="Microsoft Teams app capabilities for bot." link="~/bots/what-are-bots.md" border="false"::: :::row-end:::- + :::row::: :::image type="content" source="~/assets/images/overview/flowchart-message-extension.png" alt-text="Microsoft Teams app capabilities for message extension." link="~/messaging-extensions/what-are-messaging-extensions.md" border="false"::: :::row-end:::- + :::row::: :::image type="content" source="~/assets/images/overview/flowchart-adaptive-card.png" alt-text="Microsoft Teams app capabilities for adaptive cards." link="~/task-modules-and-cards/cards/cards-reference.md#adaptive-card" border="false"::: :::row-end:::- + :::row::: :::image type="content" source="~/assets/images/overview/flowchart-apps-for-meetings.png" alt-text="Microsoft Teams app capabilities for meetings." link="~/apps-in-teams-meetings/teams-apps-in-meetings.md" border="false"::: :::row-end:::- + :::row::: :::image type="content" source="~/assets/images/overview/flowchart-webhook-and-connectors.png" alt-text="Microsoft Teams app capabilities for webhooks and connectors." link="~/webhooks-and-connectors/what-are-webhooks-and-connectors.md" border="false"::: :::row-end:::- + :::row::: :::image type="content" source="~/assets/images/overview/flowchart-graph-conversational-interface.png" alt-text="Microsoft Teams app capabilities for graph conversational interface." link="/graph/overview" border="false"::: :::row-end::: |
| platform | Planning Checklist | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/concepts/design/planning-checklist.md | Last updated 07/28/2022 # Teams app planning checklist -An app's lifecycle extends from planning your app to eventually deploying it, and beyond. It takes more than knowing your user and requirements to plan your app. Depending on your app needs, you may also consider planning for future updates. +An app's lifecycle extends from planning your app to eventually deploying it, and beyond. It takes more than knowing your users and requirements to plan your app. Depending on your app needs, you might also consider planning for future updates. Let's take a practical look at planning for an app's lifecycle. Suggestion: Options that help select the correct environment based on app needs. <details> <summary>Plan analytics for your app</summary> -As a developer whoΓÇÖs building an app for millions of Microsoft Teams users to achieve specific business or customer goals and distributing it using one or more of the many distribution options available to you, you will be interested to measure how your app is performing in the real-world once published. You will also be interested in monitoring who is interested in your app, which users and organizations are using your app, how are users engaging with your app, which users have churned away after using your app for some time and many such data points. Once you know this, you can analyze the data against your business goals, take corrective action by fixing issues and intervening in the user journey or plan further enhancements to your app. +As a developer whoΓÇÖs building an app for millions of Microsoft Teams users to achieve specific business or customer goals and distributing it using one or more of the many distribution options available to you, you are interested to measure how your app is performing in the real-world once published. You'll also be interested in monitoring who is interested in your app, which users and organizations are using your app, how are users engaging with your app, which users have churned away after using your app for some time and many such data points. Once you know this, you can analyze the data against your business goals, take corrective action by fixing issues and intervening in the user journey or plan further enhancements to your app. For more information, see [planning analytics](overview-analytics.md). </details> You can provide your Microsoft Teams app to an individual, team, organization, o Suggestion: Options that help determine the best distribution model. +</details> +<br> +<details> +<summary>Plan for app notifications</summary> ++You can send notifications to Teams users in multiple ways. Notifications are a simple way to engage users regularly. For more information, see [plan to send app notifications](design-app-notification.md). + </details> ## Plan for hosting your Teams app Teams doesn't host your app. When a user installs your app in Teams, they instal - **Plan the onboarding experience**: Craft your onboarding experience with your key users in mind. How you introduce a chat bot installed in a channel with a thousand people, is different when it's installed in a one-to-one chat. -- **Plan for the future**: Identify new features the user will prefer in the current solution. Any new features may impact app design and architecture.+- **Plan for the future**: Identify new features the user prefers in the current solution. Any new features might impact app design and architecture. ## See also |
| platform | Understand Use Cases | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/concepts/design/understand-use-cases.md | There are a few options for [incorporating your app into the Teams calling exper #### Microsoft Graph for Teams -The [Microsoft Graph API for Teams](/graph/teams-concept-overview) provides access to information about teams, channels, users, and messages that help you to create or enhance features for your app. +The [Microsoft Graph API for Teams](/graph/teams-concept-overview) provides access to information about teams, channels, users, and messages that helps you to create or enhance features for your app. The notification APIs provides a simple way to send notifications from your app to the Teams activity. :::column-end::: |
| platform | Build Interactive Notification Bot | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/get-started/build-interactive-notification-bot.md | + + Title: Build an interactive notification bot +description: Sends messages in Teams channel or group chat or personal chat. +ms.localizationpriority: medium Last updated : 06/07/2023++++# Build an interactive notification bot ++For an interactive notification, a bot sends messages in a Teams channel, group chat, or personal chat. You can trigger an interactive notification bot with an HTTP request, such as cards or texts. For proactive notifications from tab apps, use [activity feed notifications](/graph/teams-send-activityfeednotifications). +++In this tutorial, learn about an interactive notification bot app in one of the following ways. ++* **GitHub Codespaces**: The codespace instance allows you to experience a Teams app instantaneously. It opens Visual Studio Code (VS Code) where the Teams Toolkit extension, the app source code, and all the dependencies are pre-packaged for you. +* **Step-by-step guide**: Allows you to set up your development environment and build a Teams app from the start. ++# [GitHub Codespaces](#tab/teamstoolkitcodespaces) ++Before you create your codespace, ensure that you have the following prerequisites: ++* A GitHub account to create your codespace instance +* A [Microsoft 365 account](https://developer.microsoft.com/microsoft-365/dev-program) with custom app upload permission +* A [Microsoft 365 tenant](../concepts/build-and-test/prepare-your-o365-tenant.md) ++> [!TIP] +> +> [GitHub Codespaces](https://github.com/features/codespaces) offers a free plan with a fixed amount of usage per month. If you need to free up more space, go to [github.com/codespaces](https://github.com/codespaces) and delete the codespace that you no longer need. ++To create an interactive Teams notification bot with GitHub Codespaces, follow these steps: ++1. Select the following button to open GitHub Codespaces. ++ <a href="https://github.com/codespaces/new?hide_repo_select=true&ref=v3&repo=348288141&machine=basicLinux32gb&location=WestUs2&devcontainer_path=.devcontainer%2Fnotification-codespaces%2Fdevcontainer.json&resume=1" target="_blank"><img src="https://github.com/codespaces/badge.svg" alt="Open hello-world tab in GitHub Codespaces"></a> ++ You might be asked to sign in to GitHub account if you haven't already. ++1. Select **Create new codespace**. ++ :::image type="content" source="../assets/images/get-started/codespace.png" alt-text="Screenshot shows you the GitHub page to create a codespace for bot."::: ++ The **Setting up your codespace** page appears. ++ :::image type="content" source="../assets/images/get-started/building-codespace.png" alt-text="Screenshot shows you the codespace building your notification bot."::: ++ Teams Toolkit prepares an interactive notification bot project for you and opens it in VS Code in the browser. The Teams Toolkit icon appears in the activity bar of VS Code. ++1. Select **Sign in to your Microsoft 365** and **Sign in to Azure** to sign in with your Microsoft 365 account. ++ :::image type="content" source="../assets/images/get-started/toolkit-in-browser-sign-in.png" alt-text="Screenshot shows you the Teams Toolkit window in browser to sign in."lightbox="../assets/images/get-started/add-tab-in-teams.png"::: ++ > [!NOTE] + > + > When you build your app, GitHub Codespaces loads it to the Teams client in a new tab. If your browser blocks pop-up tabs or windows, you need to allow pop-ups for your app to open. ++1. Select **Preview your Teams App (F5)**. ++ :::image type="content" source="../assets/images/get-started/toolkit-in-browser.png" alt-text="Screenshot shows you the Teams Toolkit window in browser with your notification bot."lightbox="../assets/images/get-started/toolkit-in-browser.png"::: ++ GitHub Codespaces builds your interactive notification bot app, loads it to Teams client, and opens it in a separate browser tab. ++1. Once the app dialog appears, select **Add** to install your interactive notification bot in Teams. ++ :::image type="content" source="../assets/images/get-started/codespace/bot-teams.png" alt-text="Screenshot shows you the notification bot loaded in the Teams client."::: ++1. Open a new terminal in your codespace and run the following command to trigger an event for sending an interactive notification to your bot: ++ ```bash + curl -X POST http://localhost:3978/api/notification + ``` ++ > [!TIP] + > + > In real time, events are triggered by an external source, such as a third-party API that cause the notification bot to send the user an interactive notification. To emulate an event trigger, you can send an event manually through curl commands on terminal. ++ The notification bot app sends an interactive notification as an Adaptive Card to your Teams client: ++ :::image type="content" source="../assets/images/get-started/codespace/notification-bot.png" alt-text="Screenshot shows your notification bot loaded in the Teams client."::: ++ You've now successfully created an interactive notification bot and loaded it in the Teams client. ++# [Step-by-step guide](#tab/step-by-step-guide) ++If you want to learn how to start a project with Teams Toolkit from the beginning, you need to set up your development environment. Select the following button to start building your interactive notification bot. ++> [!div class="nextstepaction"] +> [Start building an interactive notification bot](../sbs-gs-notificationbot.yml) ++++If you want to build a message extension, go to: ++> [!div class="nextstepaction"] +> [Build message extension](build-message-extension.md) ++If you want to build basic tab app, go to: ++> [!div class="nextstepaction"] +> [Build your basic tab app](build-basic-tab-app.md) |
| platform | Choose What Suits You | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/get-started/choose-what-suits-you.md | -You've built your first tab app, notification bot, and message extension. You can build a Teams app as per your app's requirements. Based on factors such as business needs, development environment, and domain knowledge, select the environment and tools to build your app. +You've built your first tab app, interactive notification bot, and message extension. You can build a Teams app as per your app's requirements. Based on factors such as business needs, development environment, and domain knowledge, select the environment and tools to build your app. A Teams app offers you the flexibility of choosing your build environment. It includes tools, framework, and languages to approach your app development. Build your Teams app in the environment that's best suited for your app. You can even select a combination. For example, you can use Teams Toolkit to build an app with JavaScript and host it on a SharePoint site. You can use various tools and services to build your app. Following is an exampl 1. Plan your project and figure out the requirement. 1. Design your app. Use Teams UI Kit and UI Library for designing tabs UI. 1. Build your app with JavaScript using Teams Toolkit.-1. Extend functionality by adding more Teams capabilities and Microsoft 365 data with :::image type="icon" source="../assets/icons/graph-small-icon.png"::: Microsoft Graph. +1. Extend functionality by adding more Teams capabilities, send activity feed notifications, and use Microsoft 365 data with :::image type="icon" source="../assets/icons/graph-small-icon.png"::: Microsoft Graph. 1. Test the app on a developer tenant with sample user data. 1. Deploy the app to Azure. 1. Manage and publish the app to Microsoft Teams Store with Developer Portal. Monetize your app with options, such as SaaS offers, in-app purchases, and more. To start building your Teams app, you can select the tools and SDKs based on you | App capabilities | User interactions | Recommended tools | SDKs | Languages | |--|-|--|--|--| | **Tabs** | A full-screen embedded web experience. | VS Code or Visual Studio with Teams Toolkit extension, or [TeamsFx CLI](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/cli/user-manual.md) if you prefer using CLI | [Teams JavaScript client library](/javascript/api/overview/msteams-client?view=msteams-client-js-latest&preserve-view=true) for UI functionalities, SharePoint Framework (SPFx), and Microsoft Graph SDK | C#, TypeScript, and JavaScript (including React) |-| **Bots** | A chat bot that converses with members. |VS Code or Visual Studio with Teams Toolkit extension, or [TeamsFx CLI](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/cli/user-manual.md) if you prefer using CLI | [TeamsFx SDK](/javascript/api/@microsoft/teamsfx/?view=msteams-client-js-latest&preserve-view=true), [Bot Framework SDK](https://dev.botframework.com/), Teams AI library, and Microsoft Graph SDK | C#, TypeScript, and JavaScript | -| **Message extensions** | Shortcuts for inserting external content into a conversation or taking action on messages. | VS Code or Visual Studio with Teams Toolkit extension, or [TeamsFx CLI](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/cli/user-manual.md) if you prefer using CLI | [TeamsFx SDK](/javascript/api/@microsoft/teamsfx/?view=msteams-client-js-latest&preserve-view=true), [Bot Framework SDK](https://dev.botframework.com/), Teams AI library, and Microsoft Graph SDK | C#, TypeScript, and JavaScript | +| **Bots** | A chat bot that converses with members. |VS Code or Visual Studio with Teams Toolkit extension, or [TeamsFx CLI](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/cli/user-manual.md) if you prefer using CLI | [TeamsFx SDK](/javascript/api/@microsoft/teamsfx/?view=msteams-client-js-latest&preserve-view=true), [Bot Framework SDK](https://dev.botframework.com/), [Teams AI library](../bots/how-to/Teams%20conversational%20AI/teams-conversation-ai-overview.md), and Microsoft Graph SDK | C#, TypeScript, and JavaScript | +| **Message extensions** | Shortcuts for inserting external content into a conversation or taking action on messages. | VS Code or Visual Studio with Teams Toolkit extension, or [TeamsFx CLI](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/cli/user-manual.md) if you prefer using CLI | [TeamsFx SDK](/javascript/api/@microsoft/teamsfx/?view=msteams-client-js-latest&preserve-view=true), [Bot Framework SDK](https://dev.botframework.com/), [Teams AI library](../bots/how-to/Teams%20conversational%20AI/teams-conversation-ai-overview.md), and Microsoft Graph SDK | C#, TypeScript, and JavaScript | > [!NOTE] > |
| platform | Overview Explore | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/overview-explore.md | With Teams, you can build your app in a feature-rich environment. Using Teams as | Feature | Description | Useful for | | | | |-|Tabs | Tabs are Teams-aware webpages embedded in Microsoft Teams. You can add them as part of a channel inside a team, group chat, or personal app for an individual user. | Personal tab, channel or group tab, Stageview, and link unfurling. | -| Bots | A bot is also referred to as a chatbot or conversational bot. It's an app that runs simple and repetitive automated tasks done by the users. A bot interaction can be a quick question and answer, or it can be a complex conversation that provides access to services. | Customer service, information about the weather, make dinner reservations, or provide travel information. | +|Tabs | Tabs are Teams-aware webpages embedded in Microsoft Teams. You can add them as part of a channel inside a team, group chat, or personal app for an individual user. | Personal tab, channel or group tab, Stage View, and link unfurling. | +| Bots | A bot, also known as a chatbot or conversational bot, has evolved with artificial intelligence to understand and respond to users in natural language for dynamic conversations. A bot interaction can be a quick question and answer, or it can be a complex conversation that provides access to services. | Customer service, content generation such as new sales presentations or code, personalized guidance for your app, complex financial analysis, and automation of tasks. | | Message extension | Message extensions let the users interact with your web service Teams client. They search or start actions in an external system. You can send the result of the interaction to the Teams client as a richly formatted card. | Reserve a resource and allow the channel to know the reserved time slot. Search for a work item, and share it with the group as an Adaptive Card. Create a bug in your tracking system based on a Teams message, assign that bug to a user, and send a card to the conversation thread with the bug's details. | |Meeting extensions | You can create apps to make meetings more productive. | Ask people to complete a survey during a call or send a quick reminder that doesnΓÇÖt interrupt the flow of the meeting. | | Personal app | A personal app is a dedicated space (tab) or bot to help users focus on their own tasks or view activities important to them. | OneNote is a personal app that gives you a private workspace within Teams. Planner offers a bird's eye view of all your tasks, across boards that you or your team have added as channel tabs. | | Webhooks and connectors | Communicate with external apps, and send or receive notifications and messages from other apps. | Subscribe to receive notifications and messages from your web services. |-| Microsoft Graph | Microsoft Graph is the gateway to data and intelligence in Microsoft 365 and can be incorporated in any kind of Teams app. | Create, manage, find, and archive large number of teams and populate them with users and channels. | +| Microsoft Graph | Microsoft Graph APIs enable Teams apps to build collaborative features with the intelligence of Microsoft 365 data and engage users regularly through activity feed notifications. | Send activity feed notifications, export or import messages, get meeting transcripts and recordings, use resource-specific consent (RSC) permissions, CRUD (create, read, update, and delete) users, chats, channels, and apps. | | Adaptive Card | Cards help you organize information into groups and give users the opportunity to interact with specific parts of the information. | Sharing using text and images; gathering information using input forms. | | Dialogs (referred as task modules in TeamsJS v1.x) | Dialogs permit you to create modal pop-up experiences in your Teams application. | Run your own custom HTML or JavaScript code. Show an <`iframe`>-based widget such as a YouTube or Microsoft Stream video. | |
| platform | Manifest Schema | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/resources/schema/manifest-schema.md | A list of commands that your bot can recommend to users. The object is an array |`items.scopes`|Array of enums|3|✔️|Specifies the scope for which the command list is valid. Options are `team`, `personal`, and `groupChat`.| |`items.commands`|Array of objects|10|✔️|An array of commands the bot supports:<br>`title`: the bot command name (string, 32)<br>`description`: a simple description or example of the command syntax and its argument (string, 128).| +> [!NOTE] +> Teams mobile client doesn't support the bot app when there is no value in the `commandLists` property. + ### bots.commandLists.commands |Name| Type| Maximum size | Required | Description| |
| platform | Access Teams Context | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/tabs/how-to/access-teams-context.md | Your tab requires contextual information to display relevant content: * Basic information about the user, team, or company. * Locale and theme information.-* The `page.id` and `page.subPageId` that identify what is in this tab (known as `entityId` and `subEntityId` before TeamsJS v.2.0.0). +* The `page.id` and `page.subPageId` that identify what is in this tab (known as `entityId` and `subEntityId` before TeamsJS v2.0.0). ## User context You can access context information in two ways: Use placeholders in your configuration or content URLs. Microsoft Teams replaces the placeholders with the relevant values when determining the actual configuration or content URL. The available placeholders include all fields on the [context](/javascript/api/@microsoft/teams-js/microsoftteams.context?view=msteams-client-js-latest&preserve-view=true) object. Common placeholders include the following properties: -* [{page.id}](/javascript/api/@microsoft/teams-js/app.pageinfo#@microsoft-teams-js-app-pageinfo-id): The developer-defined unique ID for the page defined when first [configuring the page](~/tabs/how-to/create-tab-pages/configuration-page.md). (Known as `{entityId}` before TeamsJS v.2.0.0). -* [{page.subPageId}](/javascript/api/@microsoft/teams-js/app.pageinfo#@microsoft-teams-js-app-pageinfo-subpageid): The developer-defined unique ID for the subpage this content points defined when generating a [deep link](~/concepts/build-and-test/deep-links.md) for a specific item within the page. (Known as `{subEntityId}` before TeamsJS v.2.0.0). -* [{user.loginHint}](/javascript/api/@microsoft/teams-js/app.userinfo#@microsoft-teams-js-app-userinfo-loginhint): A value suitable as a sign in hint for Microsoft Entra ID. This is usually the sign in name of the current user in their home tenant. (Known as `{loginHint}` before TeamsJS v.2.0.0). -* [{user.userPrincipalName}](/javascript/api/@microsoft/teams-js/app.userinfo#@microsoft-teams-js-app-userinfo-userprincipalname): The User Principal Name of the current user in the current tenant. (Known as `{userPrincipalName}` before TeamsJS v.2.0.0). -* [{user.id}](/javascript/api/@microsoft/teams-js/app.userinfo#@microsoft-teams-js-app-userinfo-id): The Microsoft Entra object ID of the current user in the current tenant. (Known as `{userObjectId}` before TeamsJS v.2.0.0). -* [{app.theme}](/javascript/api/@microsoft/teams-js/app.appinfo#@microsoft-teams-js-app-appinfo-theme): The current user interface (UI) theme such as `default`, `dark`, or `contrast`. (Known as `{theme}` before TeamsJS v.2.0.0). -* [{team.groupId}](/javascript/api/@microsoft/teams-js/app.teaminfo#@microsoft-teams-js-app-teaminfo-groupid): The ID of the Microsoft 365 group in which the tab resides. (Known as `{groupId}` before TeamsJS v.2.0.0) -* [{user.tenant.id}](/javascript/api/@microsoft/teams-js/app.tenantinfo#@microsoft-teams-js-app-tenantinfo-id): The Microsoft Entra tenant ID of the current user. (Known as `{tid}` before TeamsJS v.2.0.0). -* [{app.locale}](/javascript/api/@microsoft/teams-js/app.appinfo#@microsoft-teams-js-app-appinfo-locale): The current locale of the user formatted as *languageId-countryId*, for example `en-us`. (Known as `{locale}` before TeamsJS v.2.0.0). +* [{page.id}](/javascript/api/@microsoft/teams-js/app.pageinfo#@microsoft-teams-js-app-pageinfo-id): The developer-defined unique ID for the page defined when first [configuring the page](~/tabs/how-to/create-tab-pages/configuration-page.md). (Known as `{entityId}` before TeamsJS v2.0.0). +* [{page.subPageId}](/javascript/api/@microsoft/teams-js/app.pageinfo#@microsoft-teams-js-app-pageinfo-subpageid): The developer-defined unique ID for the subpage this content points defined when generating a [deep link](~/concepts/build-and-test/deep-links.md) for a specific item within the page. (Known as `{subEntityId}` before TeamsJS v2.0.0). +* [{user.loginHint}](/javascript/api/@microsoft/teams-js/app.userinfo#@microsoft-teams-js-app-userinfo-loginhint): A value suitable as a sign in hint for Microsoft Entra ID. This is usually the sign in name of the current user in their home tenant. (Known as `{loginHint}` before TeamsJS v2.0.0). +* [{user.userPrincipalName}](/javascript/api/@microsoft/teams-js/app.userinfo#@microsoft-teams-js-app-userinfo-userprincipalname): The User Principal Name of the current user in the current tenant. (Known as `{userPrincipalName}` before TeamsJS v2.0.0). +* [{user.id}](/javascript/api/@microsoft/teams-js/app.userinfo#@microsoft-teams-js-app-userinfo-id): The Microsoft Entra object ID of the current user in the current tenant. (Known as `{userObjectId}` before TeamsJS v2.0.0). +* [{app.theme}](/javascript/api/@microsoft/teams-js/app.appinfo#@microsoft-teams-js-app-appinfo-theme): The current user interface (UI) theme such as `default`, `dark`, or `contrast`. (Known as `{theme}` before TeamsJS v2.0.0). +* [{team.groupId}](/javascript/api/@microsoft/teams-js/app.teaminfo#@microsoft-teams-js-app-teaminfo-groupid): The ID of the Microsoft 365 group in which the tab resides. (Known as `{groupId}` before TeamsJS v2.0.0) +* [{user.tenant.id}](/javascript/api/@microsoft/teams-js/app.tenantinfo#@microsoft-teams-js-app-tenantinfo-id): The Microsoft Entra tenant ID of the current user. (Known as `{tid}` before TeamsJS v2.0.0). +* [{app.locale}](/javascript/api/@microsoft/teams-js/app.appinfo#@microsoft-teams-js-app-appinfo-locale): The current locale of the user formatted as *languageId-countryId*, for example `en-us`. (Known as `{locale}` before TeamsJS v2.0.0). > [!NOTE]-> The previous `{upn}` placeholder is now deprecated. For backward compatibility, it is currently a synonym for `{user.loginHint}`. +> - The previous `{upn}` placeholder is now deprecated. For backward compatibility, it is currently a synonym for `{user.loginHint}`. +> - Mobile (Android and iOS) versions of Microsoft Teams currently support only TeamsJS v1.x.x placeholders. For example, in your app manifest if you set your tab *configurationUrl* attribute to `"https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}"` and the signed-in user has the following attributes: You can also retrieve the context information using the [Microsoft Teams JavaScr } ``` -# [TeamsJS v1](#tab/Json-v1) +# [TeamsJS v1.x.x](#tab/Json-v1) The information can be retrieved by calling `microsoftTeams.getContext(function(context) { /* ... */ })`. async function example() { /*...*/ } ```--# [TeamsJS v1](#tab/teamsjs-v1) +# [TeamsJS v1.x.x](#tab/teamsjs-v1) ## TypeScript |
| platform | What Are Webhooks And Connectors | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/webhooks-and-connectors/what-are-webhooks-and-connectors.md | Webhooks help Teams to integrate with external apps. With Outgoing Webhooks, you Connectors allow users to subscribe to receive notifications and messages from the web services. They expose the HTTPS endpoint for the service to post messages to Teams channels, typically in the form of cards. +> [!NOTE] +> Connectors can't update messages or send messages as responses to existing messages. + ### Incoming Webhooks Incoming Webhooks help in posting messages from apps to Teams. If Incoming Webhooks are enabled for a team in any channel, it exposes the HTTPS endpoint, that accepts correctly formatted JSON and inserts the messages to that channel. For example, you can create an Incoming Webhook in your DevOps channel, configure your build, and simultaneously deploy and monitor services to send alerts. #### Notification bot or Incoming Webhook -Before you start to learn how to build Incoming Webhooks, you may also want to know that you can build a notification bot using Teams Toolkit. Notification bots can enable more customizable experience to meet different business scenarios. --Learn more about the differences between a notification bot and Incoming Webhook so that you can choose the right solutions for your scenarios: --| | Notification bot | Incoming Webhook | -| | | | -| What is it? | A Teams app | A Teams feature | -| Installation required | Yes | No | -| Suitable scenarios | ΓÇó Receive regular notifications and messages periodically, for example, receive daily notification of team tasks. <br> ΓÇó Receive notifications and messages based on real events. For example, once teammates upload files, you receive notifications. | Communicate with external apps and receive notifications and messages from other apps. | -| Scope configuration | ΓÇó Teams channel <br> ΓÇó Group chat <br> ΓÇó Personal chat | Teams channel | -| Message process | A notification bot works as a Teams application. You can define your business logic to process data and show data in a customized format. | Webhook is a Teams feature rather than a Teams application, so it only receives and shows data without processing. | -| Retrieve Teams context | Notification bot can retrieve Teams context such as the channel or user information, messages, etc. | No | -| Send Adaptive Card | Yes | Yes | -| Send a welcome message | Yes | No | -| Trigger supported | All triggers are supported. If you use Teams Toolkit, you can quickly get a template project with the following triggers: <br> ΓÇó Time trigger hosted on Azure functions. <br> ΓÇó Restify HTTP trigger hosted on Azure app service. <br> ΓÇó HTTP trigger hosted on Azure Functions. | All triggers are supported. | -| Building Tools | ΓÇó [Teams Toolkit Overview for Visual Studio Code](../toolkit/teams-toolkit-fundamentals.md) <br> ΓÇó[Teams Toolkit Overview for Visual Studio](../toolkit/toolkit-v4/teams-toolkit-fundamentals-vs.md) <br> ΓÇó [Teams Toolkit CLI](../toolkit/Teams-Toolkit-CLI.md) <br> ΓÇó [TeamsFx SDK](../toolkit/TeamsFx-SDK.md) | No tools are required. | -| Cloud resource required | Azure Bot Framework | No resources are required. | -| Tutorial | [Build notification bot with JavaScript](../sbs-gs-notificationbot.yml) | [Incoming Webhook notification sample](https://github.com/OfficeDev/TeamsFx-Samples/tree/dev/incoming-webhook-notification) | +Before you start to learn how to build Incoming Webhooks, you may also want to know that you can build a notification bot using Teams Toolkit or send activity feed notifications using Microsoft Graph API. Notification bots and activity feed notifications can enable more customizable experience to meet different business scenarios. For more information, see [plan to send app notifications](../concepts/design/design-app-notification.md). ++| | Notification API | Notification bot | Incoming Webhook | +| | | | | +| What is it? | A RESTful web API | A Teams app | A Teams feature | +| Installation required | Yes | Yes | No | +| Suitable scenarios | ΓÇó Notify users about urgent or critical information. <br> ΓÇó Display rich content that requires user action in the main pane of Teams. <br> ΓÇó Receive operating system notification with sound. <br> ΓÇó Localized preview text in Activity. | ΓÇó Receive regular notifications and messages periodically, for example, receive daily notification of team tasks. <br> ΓÇó Receive notifications and messages based on real events. For example, once teammates upload files, you receive notifications. | Communicate with external apps and receive notifications and messages from other apps. | +| Scope configuration | ΓÇó A single user <br> ΓÇó A list of users <br> ΓÇó Users in a chat <br> ΓÇó Users in a team | ΓÇó Teams channel <br> ΓÇó Group chat <br> ΓÇó Personal chat | Teams channel | +| Message process |A Teams app makes a REST API call to trigger a notification in Activity in Teams. The API call passes the deep link to load content in the main pane. | A notification bot works as a Teams application. You can define your business logic to process data and show data in a customized format. | Webhook is a Teams feature rather than a Teams application, so it only receives and shows data without processing. | +| Retrieve Teams context |App can use Graph APIs to work with Microsoft 365 data. | Notification bot can retrieve Teams context such as channel or user information and messages. | No | +| Send Adaptive Card | No | Yes | Yes | +| Send a welcome message | Yes | Yes | No | +| Trigger supported |All triggers are supported. | All triggers are supported. <br> If you use Teams Toolkit, you can quickly get a template project with the following triggers: <br> ΓÇó Time trigger hosted on Azure functions. <br> ΓÇó Restify HTTP trigger hosted on Azure app service. <br> ΓÇó HTTP trigger hosted on Azure Functions.| All triggers are supported.| +| Building Tools |[Quick start - Microsoft Graph](https://developer.microsoft.com/graph/quick-start) | ΓÇó [Teams Toolkit Overview for Visual Studio Code](../toolkit/teams-toolkit-fundamentals.md) <br> ΓÇó [Teams Toolkit Overview for Visual Studio](../toolkit/toolkit-v4/teams-toolkit-fundamentals-vs.md) <br> ΓÇó [Teams Toolkit CLI](../toolkit/Teams-Toolkit-CLI.md) <br> ΓÇó [TeamsFx SDK](../toolkit/TeamsFx-SDK.md) | No tools are required. | +| Cloud resource required | Microsoft Entra app | Azure Bot Framework | No resources are required. | +| Tutorial | ΓÇó [Send activity feed notifications to users in Microsoft Teams](/graph/teams-send-activityfeednotifications) <br> ΓÇó [Send activity feed notification](../sbs-graphactivity-feedbroadcast.yml) | [Build notification bot with JavaScript](../sbs-gs-notificationbot.yml) | [Incoming Webhook notification sample](https://github.com/OfficeDev/TeamsFx-Samples/tree/dev/incoming-webhook-notification) | ### Connectors for Microsoft 365 Groups |