Proactive messages

Important

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 is not in response to a request from a user. This can include messages, such as:

  • Welcome messages
  • Notifications
  • Scheduled messages

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 required, 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 is 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 cannot create a new group chat or a new channel in a team with proactive messaging.

To send a proactive message

  1. Get the user ID, team ID, or channel ID, if required.
  2. Create the conversation, if required.
  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 cannot 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 does not exist or you do not know the conversationId. You must only create the conversation once and store the conversationId value or conversationReference object.

After the conversation is created, you must get the conversation ID.

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 are 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 have sent the proactive message, you must follow these best practices while sending proactive messages for better information exchange between users and the bot.

Best practices for proactive messaging

Sending proactive messages to users is a very effective way to communicate with your users. However, from their perspective, this message can appear completely unprompted, and in the case of welcome messages, it is the first time they have interacted with your app. Therefore, it is very important to use proactive messaging sparingly, not spam your users, and provide enough information to let users understand why they are receiving the messages.

Welcome messages

When proactive messaging is used to send a welcome message to a user, there is no context for why the users receive the message. This is also the first time users interact with your app. It is an opportunity to create a good first impression. The best welcome messages must include:

  • Why a user is receiving the message: It must be very clear to the user why they are receiving the message. If your bot was installed in a channel and you sent a welcome message to all users, 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 to users blocking your bot. Write to the point and clear welcome messages. Iterate on the welcome messages if they are not 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 have 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 was updated to cause 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 are 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

Note

Proactively installing apps using Graph is currently in beta.

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 is also a Microsoft .NET framework sample on the GitHub platform.

Samples

The following code shows how to send proactive messages:

[Route("api/notify")]
[ApiController]
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
        // https://aka.ms/BotTrustServiceUrl
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Note

Currently bots cannot create a group chat through bot APIs or Graph. createConversation is available only for 1:1 chats.

Code sample

The following table provides a simple code sample that incorporate 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

See also

Teams proactive messaging code samples

Next step