| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| platform | Calls Meetings Bots Overview | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/bots/calls-and-meetings/calls-meetings-bots-overview.md | Real-time media refers to scenarios where media must be processed in real-time, * [Set up auto answer for Microsoft Teams Rooms on Android and Teams video phone devices](/microsoftteams/set-up-auto-answer-on-teams-android) * [Teams recording policy](/MicrosoftTeams/teams-recording-policy) * [Work with communications API in Microsoft Graph](/graph/api/resources/communications-api-overview?view=graph-rest-beta&preserve-view=true)+* [Enable an event as online meeting in Outlook calendar](/graph/outlook-calendar-online-meetings?tabs=http) |
| platform | Send Proactive Messages | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/bots/how-to/conversations/send-proactive-messages.md | Title: Send proactive messages -description: Learn how to send proactive messages with your Teams bot, install your app using Microsoft Graph and check code samples based on Bot Framework SDK v4 +description: Learn how to send proactive messages with your Teams bot, install your app using Microsoft Graph, and check code samples based on Bot Framework SDK v4. -+ ms.localizationpriority: high # Proactive messages [!INCLUDE [v4 to v3 pointer](~/includes/v4-to-v3-pointer-bots.md)] -A proactive message is any message sent by a bot that isn't in response to a request from a user. This can include messages, such as: +A proactive message is any message sent by a bot that isn't in response to a request from a user. This message can include content, such as: * Welcome messages * Notifications * Scheduled messages > [!IMPORTANT]-> Currently, bots are available in Government Community Cloud (GCC) and GCC-High but not in Department of Defense (DOD). +> Bots are available in Government Community Cloud (GCC) and GCC-High but not in Department of Defense (DOD) environments. > > For proactive messages the bots should use the following end points for government cloud environments: > > * GCC: `https://smba.infra.gcc.teams.microsoft.com/gcc`. > * GCCH: `https://smba.infra.gov.teams.microsoft.us/gcch`. -For your bot to send a proactive message to a user, group chat, or team, it must have access to send the message. For a group chat or team, the app that contains your bot must be first installed in that location. -You can [proactively install your app using Microsoft Graph](#proactively-install-your-app-using-graph) in a team, if necessary, or use an [app policy](/microsoftteams/teams-custom-app-policies-and-settings) to push apps out to teams and users in your tenant. For users, your app either must be installed for the user or your user must be part of a team where your app is installed. +To send a proactive message to a user, a group chat, or a team, your bot must have the requisite access to send the message. For a group chat or team, the app that contains your bot must be first installed in that location. ++You can [proactively install your app using Microsoft Graph](#proactively-install-your-app-using-graph) in a team, if necessary, or use a [custom app policy](/microsoftteams/teams-custom-app-policies-and-settings) to install an app in your teams and for organization's users. For certain scenarios, you must [proactively install your app using Graph](#proactively-install-your-app-using-graph). For a user to receive proactive messages, install the app for the user or make the user a part of a team in which the app is installed. Sending a proactive message is different from sending a regular message. There's no active `turnContext` to use for a reply. You must create the conversation before sending the message. For example, a new one-to-one chat or a new conversation thread in a channel. You can't create a new group chat or a new channel in a team with proactive messaging. To send a proactive message, follow these steps: 1. [Get the conversation ID](#get-the-conversation-id). 1. [Send the message](#send-the-message). -The code snippets in the [samples](#samples) section are for creating a one-to-one conversation. For links to complete working samples for both one-to-one conversations and group or channels, see [code sample](#code-sample). --For using proactive messages effectively, see [best practices for proactive messaging](#best-practices-for-proactive-messaging). For certain scenarios, you must [proactively install your app using Graph](#proactively-install-your-app-using-graph). The code snippets in the [samples](#samples) section are for creating a one-to-one conversation. For complete working samples for both one-to-one conversations and groups or channels, see [code sample](#code-sample). +The code snippets in the [samples](#samples) section are to create a one-to-one conversation. For links to samples for both one-to-one conversations and group or channels messages, see [code sample](#code-sample). To use proactive messages effectively, see [best practices for proactive messaging](#best-practices-for-proactive-messaging). ## Get the user ID, team ID, or channel ID -To create a new conversation or conversation thread in a channel, you must have the correct ID. You can receive or retrieve this ID using any of the following: +To create a new conversation or a conversation thread in a channel, you must have the correct ID. You can receive or retrieve this ID using any of the following ways: -* When your app is installed in any particular context, you receive an [`onMembersAdded` activity](~/bots/how-to/conversations/subscribe-to-conversation-events.md). +* When your app is installed in a particular context, you receive an [`onMembersAdded` activity](~/bots/how-to/conversations/subscribe-to-conversation-events.md). * When a new user is added to a context where your app is installed, you receive an [`onMembersAdded` activity](~/bots/how-to/conversations/subscribe-to-conversation-events.md). * You can retrieve the [list of channels](~/bots/how-to/get-teams-context.md) in a team where your app is installed. * You can retrieve the [list of members](~/bots/how-to/get-teams-context.md) of a team where your app is installed. * Every activity your bot receives must contain the required information. -Regardless of how you get the information, you must store the `tenantId` and either the `userId` or `channelId` to create a new conversation. You can also use the `teamId` to create a new conversation thread in the general or default channel of a team. +Regardless of how you get the information, store the `tenantId` and either the `userId` or `channelId` to create a new conversation. You can also use the `teamId` to create a new conversation thread in the general or default channel of a team. -The `userId` is unique to your bot ID and a particular user. You can't reuse the `userId` between bots. The `channelId` is global. However, your bot must be installed in the team before you can send a proactive message to a channel. +The `userId` is unique to your bot ID and a particular user. You can't reuse the `userId` between bots. The `channelId` is global. However, install the bot in the team before you can send a proactive message to a channel. -After you have the user or channel information, you must create the conversation. +Create the conversation, after you have the user or channel information. ## Create the conversation -You must create the conversation if it doesn't exist or you don't know the `conversationId`. You must only create the conversation once and store the `conversationId` value or `conversationReference` object. +Create the conversation if it doesn't exist or you don't know the `conversationId`. Create the conversation only once and store the `conversationId` value or `conversationReference` object. -You can get the conversation when the app is installed for the first time. After the conversation is created, you must get the conversation ID. The `conversationId` is available in the conversation update events. +You can get the conversation when the app is installed for the first time. After the conversation is created, [get the conversation ID](#get-the-conversation-id). The `conversationId` is available in the conversation update events. -If you don't have the `conversationId` you can [Proactively install your app using Graph](#proactively-install-your-app-using-graph) to get the `conversationId`. +If you don't have the `conversationId`, you can [Proactively install your app using Graph](#proactively-install-your-app-using-graph) to get the `conversationId`. ## Get the conversation ID After you get the appropriate address information, you can send your message. ## Send the message -Now that you have the right address information, you can send your message. If you're using the SDK, you must use the `continueConversation` method, and the `conversationId` and `tenantId` to make a direct API call. You must set the `conversationParameters` correctly to successfully send your message. See the [samples](#samples) section or use one of the samples listed in the [code sample](#code-sample) section. +Now that you have the right address information, you can send your message. If you're using the SDK, you must use the `continueConversation` method, and the `conversationId` and `tenantId` to make a direct API call. To send your message, set the `conversationParameters`. See the [samples](#samples) section or use one of the samples listed in the [code sample](#code-sample) section. > [!NOTE] > Teams doesn't support sending proactive messages using email or User Principal Name (UPN). See the following video to learn how to send proactive message from bots: <br> -> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE4NHyk] +> [!VIDEO <https://www.microsoft.com/en-us/videoplayer/embed/RE4NHyk>] <br> +### Understand who blocked, muted, or uninstalled a bot ++As a developer, you can create a report to understand which users in your organization have blocked, muted, or uninstalled a bot. This information may help your organization's admins to broadcast org-wide messages or drive app usage. ++Using Teams, you can send a proactive message to the bot to verify if a user has blocked or uninstalled a bot. If the bot is blocked or uninstalled, Teams returns a `403` response code with a `subCode: MessageWritesBlocked`. This response indicates that the message sent by the bot isn't delivered to the user. ++The response code is sent on a per-user basis and includes the identity of the user. You can compile the response codes for each user alongside their identity to create a report of all users who have blocked the bot. ++An example of a 403 response code is below. ++```http ++HTTP/1.1 403 Forbidden ++Cache-Control: no-store, must-revalidate, no-cache ++ Pragma: no-cache ++ Content-Length: 196 ++ Content-Type: application/json; charset=utf-8 ++ Server: Microsoft-HTTPAPI/2.0 ++ Strict-Transport-Security: max-age=31536000; includeSubDomains ++ MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0 ++ ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0 ++ Date: Tue, 29 Mar 2022 17:34:33 GMT ++{"errorCode":209,"message":"{\r\n \"subCode\": \"MessageWritesBlocked\",\r\n \"details\": \"Thread is blocked from message writes.\",\r\n \"errorCode\": null,\r\n \"errorSubCode\": null\r\n}"} +``` + ## Best practices for proactive messaging Sending proactive messages to the users is an effective way to communicate with your users. However, from the user's perspective, the message appears unprompted. If there's a welcome message, it will be the first time that theyΓÇÖve interacted with your app. It's important to use this functionality and provide the complete information to the user to understand the purpose of this message. ### Welcome messages -When proactive messaging is used to send a welcome message to a user, there's no context for why the users receive the message. This is also the first time users interact with your app. It's an opportunity to create a good first impression. The best welcome messages must include: +When proactive messaging is used to send a welcome message to a user, there's no context for why the user receives the message. Also, this is the first interaction of the user with your app. It's an opportunity to create a good first impression. A good user experience ensures better adoption of the app. Poor welcome messages can lead the users to block your app. Write a clear welcome message and iterate on the welcome message if it isn't having the desired effect. ++A good welcome message can include the following: -* Why a user is receiving the message? It must be clear to the user why they're receiving the message. If your bot was installed in a channel and you sent a welcome message to all users, then let them know what channel it was installed in and who installed it. +* Reason for the message - It must be clear to the user why they're receiving the message. If your bot was installed in a channel and you sent a welcome message to all users, then let them know what channel it was installed in and who installed it. -* What do you offer? Users must be able to identify what they can do with your app and what value can you bring to them. +* Your offer - Users must be able to identify what they can do with your app and what value can you bring to them. -* What should they do next? Invite users to try out a command, or interact with your app. -Poor welcome messages can lead the users to block your bot. Write to the point and clear welcome messages. Iterate on the welcome messages if they aren't having the desired effect. +* Next steps - Users should understand the next steps. For example, invite users to try out a command or interact with your app. ### 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: +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: * What happened? A clear indication of what happened to cause the notification. * What was the result? It must be clear, what item is updated to get the notification. -* Who or what triggered it? Who or what took action, that caused the notification to be sent. +* Who or what triggered it? Who or what took action, which caused the notification to be sent. * What can users do in response? Make it easy for your users to take actions based on your notifications. -* How can users opt-out? You must provide a path for users to opt-out of additional notifications. +* How can users opt-out? You must provide a path for users to opt-out of more notifications. To send messages to a large group of users, for example to your organization, proactively install your app using Graph. The following table provides a simple code sample that incorporates basic conver | Teams Conversation Basics | Demonstrates basics of conversations in Teams, including sending one-to-one proactive messages.| [View](https://github.com/microsoft/BotBuilder-Samples/blob/master/samples/csharp_dotnetcore/57.teams-conversation-bot) | [View](https://github.com/microsoft/BotBuilder-Samples/tree/master/samples/javascript_nodejs/57.teams-conversation-bot) | [View](https://github.com/microsoft/BotBuilder-Samples/blob/master/samples/python/57.teams-conversation-bot) | | Start new thread in a channel | Demonstrates creating a new thread in a channel. | [View](https://github.com/microsoft/BotBuilder-Samples/blob/master/samples/csharp_dotnetcore/58.teams-start-new-thread-in-channel) | [View](https://github.com/microsoft/BotBuilder-Samples/blob/master/samples/javascript_nodejs/58.teams-start-new-thread-in-channel) | [View](https://github.com/microsoft/BotBuilder-Samples/blob/master/samples/python/58.teams-start-thread-in-channel) | | Proactive installation of app and sending proactive notifications | This sample shows how you can use proactive installation of app for users and send proactive notifications by calling Microsoft Graph APIs. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/graph-proactive-installation/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/graph-proactive-installation/nodejs) | |-| Proactive Messaging | This is a sample which shows how to save user's conversation reference information to send proactive reminder message using Bots. | Coming soon | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-proactive-messaging-teamsfx) | - | --### Additional code sample +| Proactive Messaging | This is a sample that shows how to save user's conversation reference information to send proactive reminder message using Bots. | Coming soon | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-proactive-messaging-teamsfx) | - | > [!div class="nextstepaction"]-> [Teams proactive messaging code samples](/samples/officedev/msteams-samples-proactive-messaging/msteams-samples-proactive-messaging/) --## Step-by-step guide --Follow the step-by-step guide to [Build notification bot with JavaScript](../../../sbs-gs-notificationbot.yml), which helps you to send a proactive message from a bot. +> [More code sample of proactive messaging](/samples/officedev/msteams-samples-proactive-messaging/msteams-samples-proactive-messaging/) ## Next step Follow the step-by-step guide to [Build notification bot with JavaScript](../../ * [Respond to the task module submit action](~/messaging-extensions/how-to/action-commands/respond-to-task-module-submit.md) * [Send proactive notifications to users](/azure/bot-service/bot-builder-howto-proactive-message) * [Build your first bot app using JavaScript](../../../sbs-gs-bot.yml)-* [Build notification bot with JavaScript](../../../sbs-gs-notificationbot.yml) +* [Build notification bot with JavaScript to send a proactive message](../../../sbs-gs-notificationbot.yml) |