Skip to content

Latest commit

 

History

History
147 lines (121 loc) · 6.37 KB

README.md

File metadata and controls

147 lines (121 loc) · 6.37 KB

proactive messages sample

Bot Framework v4 proactive messages bot sample

This sample demonstrates how to send proactive messages to users by capturing a conversation reference, then using it later to initialize outbound messages.

Concepts introduced in this sample

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

Prerequisites

  • Node.js version 8.5 or higher 
    # determine node version
node --version

To try this sample

  • Clone the repository 
    git clone https://github.com/microsoft/botbuilder-samples.git
  • In a terminal, navigate to samples/javascript_nodejs/16.proactive-messages 
    cd samples/javascript_nodejs/16.proactive-messages
  • Install modules 
    npm install
  • Start the bot 
    npm start

Testing the bot using Bot Framework Emulator v4

Microsoft Bot Framework Emulator is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel.

  • Install the Bot Framework Emulator version 4.2.0 or greater from here

Connect to the bot using Bot Framework Emulator v4

  • Launch Bot Framework Emulator
  • File -> Open Bot Configuration
  • Navigate to javascript_nodejs/16.proactive-messages folder
  • Select proactive-messages.bot file

Run your bot locally and open two instances of the emulator.

  1. In the first emulator, type "run" to simulate a job being added to the queue.
  2. Copy the job number from the emulator log.
  3. In the second emulator, type "done <jobNumber>", where "<jobNumber>" is the job number, without the angle brackets, that you copied in the previous step. This will cause the bot to complete the job.
  4. Note that the bot sends a message proactively to the user in the first emulator when the job is completed.

Proactive Messages

In addition to responding to incoming messages, bots are frequently called on to send "proactive" messages based on activity, scheduled tasks, or external events.

In order to send a proactive message using Botbuilder, the bot must first capture a conversation reference from an incoming message using TurnContext.getConversationReference(). This reference can be stored for later use.

To send proactive messages, acquire a conversation reference, then use adapter.continueConversation() to create a TurnContext object that will allow the bot to deliver the new outgoing message.

Deploy this bot to Azure

Prerequisites

Provision a Bot with Azure Bot Service

After creating the bot and testing it locally, you can deploy it to Azure to make it accessible from anywhere. To deploy your bot to Azure:

# login to Azure
az login
# set you Azure subscription
az account set --subscription "<azure-subscription>"
# provision Azure Bot Services resources to host your bot
msbot clone services --name "<your_bot_name>" --code-dir "." --location westus --sdkLanguage "Node" --folder deploymentScripts/msbotClone --verbose

Publishing Changes to Azure Bot Service

As you make changes to your bot running locally, and want to deploy those change to Azure Bot Service, you can publish those change using either publish.cmd if you are on Windows or ./publish if you are on a non-Windows platform. The following is an example of publishing

# run the publish helper (non-Windows) to update Azure Bot Service.  Use publish.cmd if running on Windows
./publish

Getting Additional Help Deploying to Azure

To learn more about deploying a bot to Azure, see Deploy your bot to Azure for a complete list of deployment instructions.

Further reading