Send proactive messages

Typically, each message that a bot sends to the user directly relates to the user's prior input. In some cases, a bot may need to send the user a message that is not directly related to the current topic of conversation. These types of messages are called proactive messages.

Proactive messages can be useful in a variety of scenarios. If a bot sets a timer or reminder, it will need to notify the user when the time arrives. Or, if a bot receives a notification from an external system, it may need to communicate that information to the user immediately. For example, if the user has previously asked the bot to monitor the price of a product, the bot will alert the user if it receives notification that 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.

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.

Don't send proactive messages to users who have not previously interacted with the bot or solicited contact with the bot through another means such as e-mail or SMS.

Consider the following scenario:

how users talk

In this example, the user has previously asked the bot to monitor prices of a hotel in Las Vegas. The bot launched a background monitoring task, which has been running continuously for the past several days. In the current conversation, the user is booking a trip to London when
the background task triggers a notification message about a discount for the Las Vegas hotel. The bot interjects this information into the current conversation, making for a confusing user experience.

How should the bot have handled this situation?

  • Wait for the current travel booking to finish, then deliver the notification. This approach would be minimally disruptive, but the delay in communicating the information might cause the user to miss out on the low-price opportunity for the Las Vegas hotel.
  • Cancel the current travel booking flow and deliver the notification immediately. This approach delivers the information in a timely fashion but would likely frustrate the user by forcing them start over with their travel booking.
  • Interrupt the current booking, clearly change the topic of conversation to the hotel in Las Vegas until the user responds, and then switch back to the in-progress travel booking and continue from where it was interrupted. This approach may seem like the best choice, but it introduces complexity both for the bot developer and the user.

Most commonly, your bot will use some combination of ad hoc proactive messages and dialog-based proactive messages to handle situations like this.

Types of proactive messages

An ad hoc proactive message is the simplest type of proactive message. The bot simply interjects the message into the conversation whenever it is triggered, without any regard for whether the user is currently engaged in a separate topic of conversation with the bot and will not attempt to change the conversation in any way.

A dialog-based proactive message is more complex than an ad hoc proactive message. Before it can inject this type of proactive message into the conversation, the bot must identify the context of the existing conversation and decide how (or if) it will resume that conversation after the message interrupts.

For example, consider a bot that needs to initiate a survey at a given point in time. When that time arrives, the bot stops the existing conversation with the user and redirects the user to a SurveyDialog. The SurveyDialog is added to the top of the dialog stack and takes control of the conversation. When the user finishes all required tasks at the SurveyDialog, the SurveyDialog closes, returning control to the previous dialog, where the user can continue with the prior topic of conversation.

A dialog-based proactive message is more than just simple notification. In sending the notification, the bot changes the topic of the existing conversation. It then must decide whether to resume that conversation later, or to abandon that conversation altogether by resetting the dialog stack.

Send an ad hoc proactive message

The following code samples show how to send an ad hoc proactive message by using the Bot Builder SDK for Node.js.

To be able to send an ad hoc message to a user, the bot must first collect and save information about the user from the current conversation. The address property of the message includes all of the information that the bot will need to send an ad hoc message to the user later.

bot.dialog('adhocDialog', function(session, args) {
    var savedAddress = session.message.address;

    // (Save this information somewhere that it can be accessed later, such as in a database, or session.userData)
    session.userData.savedAddress = savedAddress;

    var message = 'Hello user, good to meet you! I now know your address and can send you notifications in the future.';


The bot can store the user data in any manner as long as the bot can access it later.

After the bot has collected information about the user, it can send an ad hoc proactive message to the user at any time. To do so, it simply retrieves the user data that it stored previously, constructs the message, and sends it.

var inMemoryStorage = new builder.MemoryBotStorage();

var bot = new builder.UniversalBot(connector)
                .set('storage', inMemoryStorage); // Register in-memory storage 

function sendProactiveMessage(address) {
    var msg = new builder.Message().address(address);
    msg.text('Hello, this is a notification');


An ad hoc proactive message can be initiated like from asynchronous triggers such as http requests, timers, queues or from anywhere else that the developer chooses.

Send a dialog-based proactive message

The following code samples show how to send a dialog-based proactive message by using the Bot Builder SDK for Node.js. You can find the complete working example in the Microsoft/BotBuilder-Samples/Node/core-proactiveMessages/startNewDialog folder.

To be able to send a dialog-based message to a user, the bot must first collect (and save) information from the current conversation. The session.message.address object includes all of the information that the bot will need to send a dialog-based proactive message to the user.

// proactiveDialog dialog
bot.dialog('proactiveDialog', function (session, args) {

    savedAddress = session.message.address;

    var message = 'Hey there, I\'m going to interrupt our conversation and start a survey in five seconds...';

    message = `You can also make me send a message by accessing: http://localhost:${server.address().port}/api/CustomWebApi`;

    setTimeout(() => {
    }, 5000);

When it is time to send the message, the bot creates a new dialog and adds it to the top of the dialog stack. The new dialog takes control of the conversation, delivers the proactive message, closes, and then returns control to the previous dialog in the stack.

// initiate a dialog proactively 
function startProactiveDialog(address) {
    bot.beginDialog(address, "*:survey");


The code sample above requires a custom file, botadapter.js, which you can download from GitHub.

The survey dialog controls the conversation until it finishes. Then, it closes (by calling session.endDialog()), thereby returning control back to the previous dialog.

// handle the proactive initiated dialog
bot.dialog('survey', function (session, args, next) {
  if (session.message.text === "done") {
    session.send("Great, back to the original conversation");
  } else {
    session.send('Hello, I\'m the survey dialog. I\'m interrupting your conversation to ask you a question. Type "done" to resume');

Sample code

For a complete sample that shows how to send proactive messages using the Bot Builder SDK for Node.js, see the Proactive Messages sample in GitHub. Within the Proactive Messages sample, simpleSendMessage shows how to send an ad-hoc proactive message and startNewDialog shows how to send a dialog-based proactive message.

Additional resources