| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| platform | Notification Bot In Teams | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/bots/how-to/conversations/notification-bot-in-teams.md | You can create notification bot in other scenarios, such as a notification can b > [!NOTE] > Bot application needs to be installed with the corresponding scope before sending notification. +[Back to top](#notification-bot-in-teams) + ## Notification based on events Bot Framework SDK provides the functionality to proactively message in Teams. TeamsFx SDK provides the functionality to manage bot's conversation references when a bot event is triggered. TeamsFx SDK recognizes the following bot events: foreach (var target in await _conversation.Notification.GetInstallationsAsync()) +[Back to top](#notification-bot-in-teams) + ## Notification bot installation A notification bot needs to be installed into a team, or a group chat, or as personal app, depending on the required scope. You need to select the installation target before adding the bot to your app. A notification bot needs to be installed into a team, or a group chat, or as per For more install options, see [configure default install options](../../../concepts/deploy-and-publish/apps-publish-overview.md#configure-default-install-options). +[Back to top](#notification-bot-in-teams) + ## Customize notification You can make the following customizations to extend the notification template to fit your business need: -<br> +* [Customize the trigger point from event source](#customize-the-trigger-point-from-event-source) +* [Customize the notification content](#customize-the-notification-content) +* [Customize where notifications are sent](#customize-where-notifications-are-sent) -<details> +### Customize the trigger point from event source -<summary><b>1. Customize the trigger point from event source</b></summary> +You can customize the following triggers: * `Restify` based notification You can make the following customizations to extend the notification template to For more information on support triggers, see [Azure Functions support triggers](/azure/azure-functions/functions-triggers-bindings?tabs=javascript). -<br> --</details> --<details> --<summary><b>2. Customize the notification content</b></summary> +### Customize the notification content The file `src/adaptiveCards/notification-default.json` defines the default Adaptive Card. You can use the [Adaptive Card designer](https://adaptivecards.io/designer/) to help visually design your Adaptive Card UI. The `src/cardModels.ts` defines a data structure that is used to load data for the Adaptive Card. The binding between the card model and the Adaptive Card is done by matching name such as `CardData.title` maps to `${title}` in the Adaptive Card. You can add, edit, or remove properties and their bindings to customize the Adaptive Card as required. You can also add new cards if needed. For more information on how to build different types of Adaptive Cards with a list or table of dynamic contents using `ColumnSet` and `FactSet`, see [Adaptive Card notification sample](<https://github.com/OfficeDev/TeamsFx-Samples/tree/ga/adaptive-card-notification>). -<br> +### Customize where notifications are sent -</details> --<details> --<summary><b>3. Customize where notifications are sent</b></summary> +You can customize sending the notification to the following targets: * Notifications to a personal chat: You can also add new cards if needed. For more information on how to build diffe > [!NOTE] > To prevent an undefined output and a missing notification, you need to include the specific person in notification installation scope. -<br> --</details> +[Back to top](#notification-bot-in-teams) ## Customize initialization foreach (var target in await _conversation.Notification.GetInstallationsAsync()) +[Back to top](#notification-bot-in-teams) + ## Customize adapter You can customize by creating your own adapter, or customize the adapter after initialization. Following is the code sample for creating your adapter: bot.adapter.onTurnError = ... ``` +[Back to top](#notification-bot-in-teams) + ## Add storage Storage can be used to implement notification connections. You can add your own storage with the help of following code sample: For sample implementation to use Azure blob storage, see [add notification stora > [!NOTE] > It's recommended to use your own shared storage for production environment. +[Back to top](#notification-bot-in-teams) + ## Add authentication for notification API If you select HTTP trigger, the scaffolded notification API doesn't have authentication or authorization enabled. Ensure that you add authentication or authorization for the API before using it for production. You can perform either of the following: If you select HTTP trigger, the scaffolded notification API doesn't have authent There can be more authentication or authorization solutions for an API, you can select as required. +[Back to top](#notification-bot-in-teams) + ## Connect to existing APIs If you don't have the required SDK, and want to invoke external APIs in your code. The `Teams: Connect to an API` command in Microsoft Visual Studio Code Teams Toolkit extension, or `teamsfx add api-connection` command in TeamsFx CLI can be used to bootstrap code to call target APIs. For more information, see [connect to existing API](../../../toolkit/add-API-connection.md#steps-to-connect-to-api). TeamsFx provides you with an [Incoming Webhook notification sample](https://gith * [Create an Incoming Webhook](../../../webhooks-and-connectors/how-to/add-incoming-webhook.md) in Teams. * Send notifications using Incoming Webhooks with Adaptive Cards. +[Back to top](#notification-bot-in-teams) + ## FAQ <br> You can extend your notification bot by defining actions and use workflow bot to </details> +[Back to top](#notification-bot-in-teams) + ## Step-by-step guide Follow the [step-by-step](../../../sbs-gs-notificationbot.yml) guide to build Teams notification bot. |
| platform | Subscribe To Conversation Events | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/bots/how-to/conversations/subscribe-to-conversation-events.md | export class MyBot extends TeamsActivityHandler { ``` # [Python](#tab/python)-* [SDK reference](/python/api/botbuilder-core/botbuilder.core.teams.teamsactivityhandler?view=botbuilder-py-latest#botbuilder-core-teams-teamsactivityhandler-on-teams-channel-deleted&preserve-view=true) +* [SDK reference](/python/api/botbuilder-core/botbuilder.core.teams.teamsactivityhandler?view=botbuilder-py-latest#botbuilder-core-teams-teamsactivityhandler-on-teams-channel-deleted&preserve-view=true) * [SDK reference](/python/api/botbuilder-core/botbuilder.core.teams.teamsactivityhandler?&preserve-view=true) protected override async Task OnTeamsMembersRemovedAsync(IList<ChannelAccount> m ``` # [TypeScript](#tab/typescript)+ [SDK reference](/javascript/api/botbuilder/teamsactivityhandler?view=botbuilder-ts-latest#botbuilder-teamsactivityhandler-onteamsmembersremovedevent&preserve-view=true) ```typescript Your bot is notified when the team is renamed. It receives a `conversationUpdate The following code shows an example of team renamed event: # [C#](#tab/dotnet)+ * [SDK reference](/dotnet/api/microsoft.bot.builder.teams.teamsactivityhandler.onteamsteamrenamedasync?view=botbuilder-dotnet-stable#definition&preserve-view=true) * [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-conversation/csharp/Bots/TeamsConversationBot.cs#L349) protected override async Task OnTeamsTeamDeletedAsync(TeamInfo teamInfo, ITurnCo ``` # [TypeScript](#tab/typescript)+ * [SDK reference](/javascript/api/botbuilder/teamsactivityhandler?view=botbuilder-ts-latest#botbuilder-teamsactivityhandler-onteamsteamdeletedevent&preserve-view=true) ```typescript export class MyBot extends TeamsActivityHandler { ``` # [Python](#tab/python)+ * [SDK reference](/python/api/botbuilder-core/botbuilder.core.teams.teamsactivityhandler?view=botbuilder-py-latest#botbuilder-core-teams-teamsactivityhandler-on-teams-team-deleted&preserve-view=true) ```python export class MyBot extends TeamsActivityHandler { ``` # [Python](#tab/python)+ * [SDK reference](/python/api/botbuilder-core/botbuilder.core.teams.teamsactivityhandler?view=botbuilder-py-latest#botbuilder-core-teams-teamsactivityhandler-on-teams-team-unarchived&preserve-view=true) ```python protected override async Task OnReactionsAddedAsync(IList<MessageReaction> messa ``` # [TypeScript](#tab/typescript)+ * [SDK reference](/javascript/api/botbuilder-core/activityhandler?view=botbuilder-ts-latest#botbuilder-core-activityhandler-onreactionsadded&preserve-view=true) * [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-conversation/nodejs/bots/teamsConversationBot.js#L55) protected override async Task OnReactionsRemovedAsync(IList<MessageReaction> mes ``` # [TypeScript](#tab/typescript)+ * [SDK reference](/javascript/api/botbuilder-core/activityhandler?view=botbuilder-ts-latest#botbuilder-core-activityhandler-onreactionsremoved&preserve-view=true) * [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-conversation/nodejs/bots/teamsConversationBot.js#L63) export class MyBot extends TeamsActivityHandler { ``` # [Python](#tab/python)+ * [SDK reference](/python/api/botbuilder-core/botbuilder.core.activityhandler?view=botbuilder-py-latest#botbuilder-core-activityhandler-on-reactions-removed&preserve-view=true) ```python In this example, the `conversation.id` of the `conversationUpdate` and `installa > The selected channel id is only set on `installationUpdate` *add* events that are sent when an app is installed into a team. # [C#](#tab/dotnet)+ * [SDK reference](/dotnet/api/microsoft.bot.builder.activityhandler.oninstallationupdateactivityasync?view=botbuilder-dotnet-stable#microsoft-bot-builder-activityhandler-oninstallationupdateactivityasync(microsoft-bot-builder-iturncontext((microsoft-bot-schema-iinstallationupdateactivity))-system-threading-cancellationtoken)&preserve-view=true) * [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-conversation/csharp/Bots/TeamsConversationBot.cs#L70-L80) When you use these install and uninstall events, there are some instances where It's important to know that new events can be added anytime in the future and your bot begins to receive them. So you must design for the possibility of receiving unexpected events. If you're using the Bot Framework SDK, your bot automatically responds with a 200 ΓÇô OK to any events you don't choose to handle. +## Handling errors in conversation events ++When a bot encounters an error while handling different events or activities, don't send messages that have no meaningful context to the conversation as shown in the following screenshot: +++In the development phase, it's always helpful to send meaningful messages in conversations, which provide additional details about a specific error for better debugging. However, in the production environment, you must log the errors or events to Azure Application Insights. For more information, see [Add telemetry to your bot](https://aka.ms/bottelemetry). + ## Code sample | **Sample name** | **Description** | **.NET** | **Node.js** | **Python** | |
| platform | Me Or Outlook Add In | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/m365-apps/me-or-outlook-add-in.md | + + Title: Decide between creating a message extension or an Outlook add-in +description: Learn how to decide whether your Microsoft 365 app should be message extension or an Outlook add-in. Last updated : 01/05/2023+++ms.localizationpriority: medium ++# Decide between creating a message extension or an Outlook add-in ++Message extensions and Outlook add-ins add rich, interactive content to email messages and meeting invitations. This article helps you decide to create a message extension or an Outlook add-in for your app based on your scenario. ++## General guidance ++# [**Outlook add-in**](#tab/outlook-add-in) ++Create an Outlook add-in if your app requires any of the following scenarios: ++* Access to the properties of email messages or calendar items. +* Ability to respond automatically to changes in the properties of email messages or calendar items. +* Fine-grained read or write access to the content of email messages and calendar items that is provided by the [Outlook add-in APIs](/office/dev/add-ins/outlook/apis). +* Read or write access to the user's mailbox. (Requires the [Outlook add-in APIs](/office/dev/add-ins/outlook/apis)) +* Ability to start up automatically in response to events without explicit user action. For more information, see [Event-based activation](/office/dev/add-ins/outlook/autolaunch). +* Ability to manipulate Outlook-specific settings, such as [custom properties](/office/dev/add-ins/outlook/metadata-for-an-outlook-add-in) and [internet headers](/office/dev/add-ins/outlook/internet-headers). +* Ability to run in messages and calendar items in [shared mailboxes or shared folders](/office/dev/add-ins/outlook/delegate-access). ++# [**Message extension**](#tab/message-extension) ++Create a message extension if your app requires any of the following scenarios: ++* Ability to work in both Teams chat and Teams calendar items as well as Outlook email messages and calendar items. +* Ability to use [Adaptive Cards](../task-modules-and-cards/cards/design-effective-cards.md) as the canvas for the content that is inserted. +* Ability to use [link unfurling](../messaging-extensions/how-to/link-unfurling.md); that is, to insert a rich preview of a link. ++++> [!NOTE] +> If your app includes scenarios from Outlook add-in and message extension, then you need to create both the apps, a message extension and an Outlook add-in (which can be hosted at the same domain and share files). We are working on a system that enables you to combine these into a single app. We'll update this article when that system is available. ++## Example applications of the guidance ++The following examples show the recommended app type for a scenario, based on the task: ++### Customer Relation Management ++| Scenario | App type | +|:--|:--| +| Save a lead that came on email into Customer Relation Management (CRM).| add-in | +| Find and insert lead details into an email or meeting invitation | message extension | +| Insert boilerplate responses from CRM into message or invitation body | message extension | +| Track email open rates (by inserting a tracking pixel). | add-in | +| Log email/meeting/engagement in Outlook into CRM. | add-in | ++### Security ++| Scenario | App type | +|:--|:--| +| Marking an email as spam .| add-in | +| Send test or mock emails for training and tracking action rates. | add-in | +| Reading or setting the [Microsoft Information Protection (MIP)](https://techcommunity.microsoft.com/t5/security-compliance-and-identity/announcing-new-microsoft-information-protection-capabilities-to/ba-p/1999692) label on an email based on business rules. | add-in | +| Encrypt and decrypt emails and attachments based on business rules. | add-in | ++### Attachment management ++| Scenario | App type | +|:--|:--| +| Save attachments in email into cloud storage. | add-in | +| Attach files from cloud storage to a message or invitation. | message extension | ++### Meeting management ++| Scenario | App type | +|:--|:--| +| Insert a meeting link into an invitation. | add-in | +| Customize a meeting link based on the recipients, the meeting time, and other contextual facts. | add-in | +| Updating a meeting link when the meeting is updated. | add-in | +| Reply with a **Meet Now** invitation. | message extension | ++### Signature management ++| Scenario | App type | +|:--|:--| +| Automatically insert a signature in mail message. | add-in | +| Customize a signature based on the recipients, new thread or reply, and other contextual facts. | add-in | +| Synchronize a signature across devices. | add-in | +| Administrator management of signatures for an organization. | add-in | |
| platform | Tab Sso Register Aad | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/tabs/how-to/authentication/tab-sso-register-aad.md | keywords: teams authentication tabs Microsoft Azure Active Directory (Azure AD) # Configure your tab app in Azure AD -Azure AD provides access to your tab app based on the app user's Teams identity. You'll need to register your tab app with Azure AD so that the app user who has signed into Teams can be given access to your tab app. +Azure Active Directory (Azure AD) provides access to your tab app based on the app user's Teams identity. You'll need to register your tab app with Azure AD so that the app user who has signed into Teams can be given access to your tab app. ## Enabling SSO in Azure AD You must define the access token version for your app. This configuration is mad 1. Enter **2** as the value for the `accessTokenAcceptedVersion` property. - :::image type="content" source="../../../assets/images/authentication/teams-sso-tabs/azure-manifest-value.png" alt-text="Value for accepted access token version"::: + > [!NOTE] + > If you've selected **Personal Microsoft accounts only** or **Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)** during app registration, update the value for the `accessTokenAcceptedVersion` property as 2. ++ :::image type="content" source="../../../assets/images/authentication/teams-sso-tabs/azure-manifest-value.png" alt-text="Value for accepted access token version"::: 1. Select **Save** |
| platform | Provision | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/provision.md | You can customize your bot or the Teams app by adding configuration snippets to #### Use an existing Azure AD app for your Teams app -You can add the following configuration snippet to `.fx\configs\config.{env}.json` file to use an Azure AD app created for your Teams app, to create an Azure AD app, see [how to use existing Azure AD app in TeamsFx project](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/fx-core/using-existing-aad.md).: +You can add the following configuration snippet to `.fx\configs\config.{env}.json` file to use an Azure AD app created for your Teams app. If you don't have an Azure AD app yet or you already have one but don't know where to find the correct value, see [how to use existing Azure AD app in TeamsFx project](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/fx-core/using-existing-aad.md): ```json+"$schema": "https://aka.ms/teamsfx-env-config-schema", +"description": "...", +"manifest": { + ... +}, +// Add code below. Note you need to replace the placeholders with real values. "auth": { "clientId": "<your Azure AD app client id>", "clientSecret": "{{$env.ENV_NAME_THAT_STORES_YOUR_SECRET}}", Perform in the following ways to customize the Teams app: #### Use an existing Azure AD app for your Teams app -You can add the following configuration snippet to `.fx\configs\config.{env}.json` file to use an Azure AD app created for your Teams app, to create an Azure AD app, see <https://aka.ms/teamsfx-existing-aad-doc>: +You can add the following configuration snippet to `.fx\configs\config.{env}.json` file to use an Azure AD app created for your Teams app. If you don't have an Azure AD app yet or you already have one but don't know where to find the correct value, see [how to use existing Azure AD app in TeamsFx project](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/fx-core/using-existing-aad.md): ```json+"$schema": "https://aka.ms/teamsfx-env-config-schema", +"description": "...", +"manifest": { + ... +}, +// Add code below. Note you need to replace the placeholders with real values. "auth": { "clientId": "<your Azure AD app client id>", "clientSecret": "{{$env.ENV_NAME_THAT_STORES_YOUR_SECRET}}", |