Proactive messages


The code samples in this section are based on version 4.6 and later versions of the Bot Framework SDK. If you are looking for documentation for earlier versions, see the bots - v3 SDK section in the Resources folder of the documentation.

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:

  • Welcome messages
  • Notifications
  • Scheduled messages


Currently, bots are available in Government Community Cloud (GCC) and GCC-High but not in Department of Defense (DOD).

For proactive messages the bots should use the following end points for government cloud environments:

  • GCC:
  • 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 in a team, if necessary, or use an app policy 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.

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 user ID, team ID, or channel ID, if necessary.
  2. Create the conversation, if necessary.
  3. Get the conversation ID.
  4. Send the message.

The code snippets in the 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.

For using proactive messages effectively, see best practices for proactive messaging. For certain scenarios, you must proactively install your app using Graph. The code snippets in the 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.

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:

  • When your app is installed in any particular context, you receive an onMembersAdded activity.
  • When a new user is added to a context where your app is installed, you receive an onMembersAdded activity.
  • You can retrieve the list of channels in a team where your app is installed.
  • You can retrieve the list of members 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.

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.

After you have the user or channel information, you must create the conversation.

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.

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.

If you don't have the conversationId you can Proactively install your app using Graph to get the conversationId.

Get the conversation ID

Use either the conversationReference object or conversationId and tenantId to send the message. You can get this ID by either creating the conversation or storing it from any activity sent to you from that context. Store this ID for reference.

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 section or use one of the samples listed in the code sample section.

Now that you've sent the proactive message, you must follow these best practices while sending proactive messages for better information exchange between users and the bot.

See the following video to learn how to send proactive message from bots:

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:

  • 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.

  • 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.

  • 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.

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:

  • 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.

  • 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.

To send messages to a large group of users, for example to your organization, proactively install your app using Graph.

Scheduled messages

When using proactive messaging to send scheduled messages to users, verify that your time zone is updated to their time zone. This ensures that the messages are delivered to the users at the relevant time. Schedule messages generally include:

  • Why is the user receiving the message? Make it easy for your users to understand the reason for which they're receiving the message.

  • What can user do next? Users can take the required action based on the message content.

Proactively install your app using Graph

Proactively message users that have previously not installed or interacted with your app. For example, you want to use the company communicator to send messages to your entire organization. In this case, you can use the Graph API to proactively install your app for your users. Cache the necessary values from the conversationUpdate event your app receives upon installation.

You can only install apps that are in your organizational app catalog or the Teams App Store.

See install apps for users in the Graph documentation and proactive bot installation and messaging in Teams with Graph. There's also a Microsoft .NET framework sample on the GitHub platform.


The following code shows how to send proactive messages:

public class NotifyController : ControllerBase
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly string _appId;
    private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

    public NotifyController(IBotFrameworkHttpAdapter adapter, IConfiguration configuration, ConcurrentDictionary<string, ConversationReference> conversationReferences)
        _adapter = adapter;
        _conversationReferences = conversationReferences;
        _appId = configuration["MicrosoftAppId"] ?? string.Empty;

    public async Task<IActionResult> Get()
        foreach (var conversationReference in _conversationReferences.Values)
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, conversationReference, BotCallback, default(CancellationToken));
        // Let the caller know proactive messages have been sent
        return new ContentResult()
            Content = "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,

    private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
        // If you encounter permission-related errors when sending this message, see
        await turnContext.SendActivityAsync("proactive hello");

Code sample

The following table provides a simple code sample that incorporates basic conversation flow into a Teams application and how to create a new conversation thread in a channel in Teams:

Sample Name Description .NET Node.js Python
Teams Conversation Basics Demonstrates basics of conversations in Teams, including sending one-to-one proactive messages. View View View
Start new thread in a channel Demonstrates creating a new thread in a channel. View View View
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 View

Additional code sample

Step-by-step guide

Follow the step-by-step guide, which helps you to send a proactive message from a bot.

Next step

See also