Invoke scenario proactively

In some use cases it's necessary for the bot to initiate a conversation with a specific user on a specific channel. In this type of scenario the bot is proactive and sends the first message. To send a proactive message, you must know the users address in advance such as their phone number (depending on the channel in use).

For example, you may want to send an SMS reminder to check if your patients are adhering to their care plan. In this case you could programatically trigger a proactive bot scenario that asks them how things are going a few days after their first treatment.

The only thing you need to send a proactive message, is the address of the recipient. You can obtain this address from previous conversations with the same user. The address object includes a set of unique identifiers specific to the User, the Conversation and the Channel in question. In some channels, such as SMS, the address is simply the phone number of the recipient.

Using SMS to initiate scenario

Using the Twilio channel, we can initiate new conversation by calling the API.

The API is secured with a JWT token that must be included in the request header (bearer) for each request. Learn more about the API secure JWT token. Once you have the JWT token, you can make a POST request to the /beginscenario endpoint.

POST

https://bot-api-<region>.healthbot.microsoft.com/api/tenants/<tenantName>/beginScenario

List of regions:

eastus
westeurope
australiaeast
centralindia
eastus2
eastus2euap
northeurope
southcentralus
southeastasia
uksouth
westcentralus
westus2

For example, bot called "contoso-demo" in region "eastus":

https://bot-api-eastus.healthbot.microsoft.com/api/tenants/contoso-demo/beginScenario

Note: You can find the tenant name in the URL of your management portal:

The POST body must include the address object, the scenario ID and any starting arguments you wish to pass to the scenario. The address object is provided by the Bot framework and depends on the channel you intend to use.

Below is a sample payload for the Twilio channel:

POST BODY

{
  "address": {
    "channelId": "sms",
    "user": {
      "id": "{{RECIPIENTS_PHONE_NUMBER}}"
    },
    "conversation": {
      "id": "{{RECIPIENTS_PHONE_NUMBER}}"
    },
    "bot": {
      "id": "{{SENDERS_PHONE_NUMBER}}"
    },
    "serviceUrl": "https://sms.botframework.com"
  },
  "scenario": "/scenarios/{{SCENARIO_ID}}",
  "args": {
    "medication": "aspirin"
  }
}

• RECIPIENTS_PHONE_NUMBER: Phone number of the message recipient (the end user) that is, +972546796311
• SENDERS_PHONE_NUMBER: Phone number of the sender of the message (The Bot) i.e. +18587790643
• SCENARIO_ID: The trigger word of the scenario you want to initiate

Values passed in "args" object are accessible in the healthcare agent service scenario editor by using the ${scenarioArgs} variable.

You can view the address object for other channels by printing to the chat thread session.message.address. You can do this by creating a simple "debugging" scenario in healthcare agent service and then triggering the scenario from the relevant channel.