Send proactive notifications to users

APPLIES TO: SDK v4

Typically, a bot sends a message to a user directly in response to receiving a message from the user. Occasionally, a bot might need to send a proactive message, a message in response to stimulus not originating from the user.

Proactive messages can be useful in various scenarios. For example, if the user has previously asked the bot to monitor the price of a product, the bot can alert the user if the price of the product has dropped by 20%. Or, if a bot requires some time to compile a response to the user's question, it may inform the user of the delay and allow the conversation to continue in the meantime. When the bot finishes compiling the response to the question, it will share that information with the user.

This article covers information about proactive messages for bots in general. For information about proactive messages in Microsoft Teams, see

• The Teams conversation bot sample in C#, JavaScript, Java, or Python.
• The Microsoft Teams documentation on how to send proactive messages.

Note

The Bot Framework JavaScript, C#, and Python SDKs will continue to be supported, however, the Java SDK is being retired with final long-term support ending in November 2023.

Existing bots built with the Java SDK will continue to function.

For new bot building, consider using Microsoft Copilot Studio and read about choosing the right copilot solution.

For more information, see The future of bot building.

Prerequisites

• Understand bot basics.
• A copy of the proactive messages sample in C#, JavaScript, Java, or Python. The sample is used to explain proactive messaging in this article.

About the proactive sample

In general, a bot as an application has a few layers:

• The web application that can accept HTTP requests and specifically supports a messaging endpoint.
• An adapter that handles connectivity with the channels.
• A handler for the turn, typically encapsulated in a bot class that handles the conversational reasoning for the bot app.

In response to an incoming message from the user, the app calls the adapter's process activity method, which creates a turn and turn context, calls its middleware pipeline, and then calls the bot's turn handler.

To initiate a proactive message, the bot application needs to be able to receive other input. The application logic for initiating a proactive message is outside the scope of the SDK. For this sample, a notify endpoint, in addition to a standard messages endpoint, is used to trigger the proactive turn.

In response to a GET request on this notify endpoint, the app calls the adapter's continue conversation method, which behaves similarly to the process activity method. The continue conversation method:

• Takes an appropriate conversation reference for the user and the callback method to use for the proactive turn.
• Creates an event activity and turn context for the proactive turn.
• Calls the adapter's middleware pipeline.
• Calls the provided callback method.
• The turn context uses the conversation reference to send any messages to the user.

The sample has a bot, a messages endpoint, and an extra endpoint that's used to send proactive messages to the user, as shown in the following illustration.

Retrieve and store the conversation reference

When the Bot Framework Emulator connects to the bot, the bot receives two conversation update activities. In the bot's conversation update activity handler, the conversation reference is retrieved and stored in a dictionary as shown below.

C#

Bots\ProactiveBot.cs

private void AddConversationReference(Activity activity)
{
    var conversationReference = activity.GetConversationReference();
    _conversationReferences.AddOrUpdate(conversationReference.User.Id, conversationReference, (key, newValue) => conversationReference);
}

protected override Task OnConversationUpdateActivityAsync(ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    AddConversationReference(turnContext.Activity as Activity);

    return base.OnConversationUpdateActivityAsync(turnContext, cancellationToken);
}

JavaScript

bots/proactiveBot.js

this.onConversationUpdate(async (context, next) => {
    this.addConversationReference(context.activity);

    await next();
});

addConversationReference(activity) {
    const conversationReference = TurnContext.getConversationReference(activity);
    this.conversationReferences[conversationReference.conversation.id] = conversationReference;
}

Java

ProactiveBot.java

@Override
protected CompletableFuture<Void> onConversationUpdateActivity(TurnContext turnContext) {
    addConversationReference(turnContext.getActivity());
    return super.onConversationUpdateActivity(turnContext);
}

// adds a ConversationReference to the shared Map.
private void addConversationReference(Activity activity) {
    ConversationReference conversationReference = activity.getConversationReference();
    conversationReferences.put(conversationReference.getUser().getId(), conversationReference);
}

Python

bots/proactive_bot.py

async def on_conversation_update_activity(self, turn_context: TurnContext):
    self._add_conversation_reference(turn_context.activity)
    return await super().on_conversation_update_activity(turn_context)

def _add_conversation_reference(self, activity: Activity):
    """
    This populates the shared Dictionary that holds conversation references. In this sample,
    this dictionary is used to send a message to members when /api/notify is hit.
    :param activity:
    :return:
    """
    conversation_reference = TurnContext.get_conversation_reference(activity)
    self.conversation_references[
        conversation_reference.user.id
    ] = conversation_reference

The conversation reference includes a conversation property that describes the conversation in which the activity exists. The conversation includes a user property that lists the users participating in the conversation, and a service URL property that indicates where replies to the current activity may be sent. A valid conversation reference is needed to send proactive messages to users. (For the Teams channel, the service URL maps to a regionalized server.)

Note

In a real-world scenario you would persist conversation references in a database instead of using an object in memory.

Send a proactive message

The second controller, the notify controller, is responsible for sending the proactive message to the user. It uses the following steps to generate a proactive message.

1. Retrieves the reference for the conversation to which to send the proactive message.
2. Calls the adapter's continue conversation method, providing the conversation reference and the turn handler delegate to use. (The continue conversation method generates a turn context for the referenced conversation and then calls the specified turn handler delegate.)
3. In the delegate, uses the turn context to send the proactive message. Here, the delegate is defined on the notify controller, and it sends the proactive message to the user.

Note

While each channel should use a stable service URL, the URL can change over time. For more information about the service URL, see the Basic activity structure and Service URL sections of the Bot Framework Activity Schema.

If the service URL changes, previous conversation references will no longer be valid and calls to continue conversation will generate an error or exception. In this case, your bot will need to acquire a new conversation reference for the user before it can send proactive messages again.

C#

Controllers\NotifyController .cs

Each time the bot's notify page is requested, the notify controller retrieves the conversation references from the dictionary. The controller then uses the ContinueConversationAsync and BotCallback methods to send the proactive message.

[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)
    {
        await turnContext.SendActivityAsync("proactive hello");
    }
}

JavaScript

index.js

Each time the server's /api/notify page is requested, the server retrieves the conversation references from the dictionary. The server then uses the continueConversation method to send the proactive message. The parameter to continueConversation is a function that serves as the bot's turn handler for this turn.

    res.setHeader('Content-Type', 'text/html');
    res.writeHead(200);
    res.write('<html><body><h1>Proactive messages have been sent.</h1></body></html>');
    res.end();
});

Java

NotifyController.java

Each time the bot's notify page is requested, the notify controller retrieves the conversation references from the dictionary. The controller then uses the continueConversation method to send the proactive message.

@RestController
public class NotifyController {
    /**
     * The BotFrameworkHttpAdapter to use. Note is is provided by dependency
     * injection via the constructor.
     *
     * @see com.microsoft.bot.integration.spring.BotDependencyConfiguration
     */
    private final BotFrameworkHttpAdapter adapter;

    private ConversationReferences conversationReferences;
    private String appId;

    @Autowired
    public NotifyController(
        BotFrameworkHttpAdapter withAdapter,
        Configuration withConfiguration,
        ConversationReferences withReferences
    ) {
        adapter = withAdapter;
        conversationReferences = withReferences;
        appId = withConfiguration.getProperty("MicrosoftAppId");
    }

    @GetMapping("/api/notify")
    public ResponseEntity<Object> proactiveMessage() {
        for (ConversationReference reference : conversationReferences.values()) {
            adapter.continueConversation(
                appId, reference, turnContext -> turnContext.sendActivity("proactive hello").thenApply(resourceResponse -> null)
            );
        }

        // Let the caller know proactive messages have been sent
        return new ResponseEntity<>(
            "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            HttpStatus.ACCEPTED
        );
    }
}

Python

Each time the bot's notify page is requested, the server retrieves the conversation references from the dictionary. The server then uses the _send_proactive_message to send the proactive message.

if __name__ == "__main__":
    try:
        web.run_app(APP, host="localhost", port=CONFIG.PORT)
    except Exception as error:
        raise error

To send a proactive message, the adapter requires an app ID for the bot. In a production environment, you can use the bot's app ID. To test the bot locally with the Emulator, you can use the empty string ("").

Test your bot

1. If you haven't done so already, install the Bot Framework Emulator.
2. Run the sample locally on your machine.
3. Start the Emulator and connect to your bot.
4. Load to your bot's api/notify page. This will generate a proactive message in the Emulator.

Additional information

Requirements

Before you can send a proactive message, your bot needs a conversation reference. Your bot can retrieve the conversation reference from any activity it has received from the user, but this typically requires the user to interact with the bot at least once before the bot can send a proactive message.

Many channels prohibit a bot from messaging a user unless the user has messaged the bot at least once. Some channels allow exceptions. For instance, the Teams channel allows your bot to send a proactive (or 1-on-1) message to individuals in an already established group conversation that includes the bot.

Design considerations

When implementing proactive messages in your bot, don't send several proactive messages within a short amount of time. Some channels enforce restrictions on how frequently a bot can send messages to the user, and will disable the bot if it violates those restrictions.

For the simplest type of proactive message, the bot interjects the message into the conversation when it's triggered, without regard for the current state or topic of conversation. In this scenario, the proactive message interrupts the normal flow of conversation.

To handle notifications more smoothly, consider other ways to integrate the notification into the conversation flow, such as setting a flag in the conversation state or adding the notification to a queue.

About the proactive turn

The continue conversation method uses the conversation reference and a turn callback handler to:

1. Create a turn in which the bot application can send the proactive message. The adapter creates an event activity for this turn, with its name set to "ContinueConversation".
2. Send the turn through the adapter's middleware pipeline.
3. Call the turn callback handler to perform custom logic.

In the proactive messages sample, the turn callback handler is defined in the notify controller and sends the message directly to the conversation, without sending the proactive activity through the bot's normal turn handler. The sample code also doesn't access or update the bot's state on the proactive turn.

Many bots are stateful and use state to manage a conversation over multiple turns. When the continue conversation method creates a turn context, the turn will have the correct user and conversation state associated with it, and you can integrate proactive turns into your bot's logic. If you need the bot logic to be aware of the proactive message, you have a few options for doing so. You can:

• Provide the bot's turn handler as the turn callback handler. The bot will then receive the "ContinueConversation" event activity.
• Use the turn callback handler to add information to the turn context first, and then call the bot's turn handler.

In both of these cases, you'll need to design your bot logic to handle the proactive event.

Next steps

Implement sequential conversation flow