20 Application-Initiated Conversations

Application-Initiated-Conversations (AIC) are conversations initiated by the ODA in response to an event it receives from an external application. The ODA uses the contents of the application’s event message to trigger one of its skills to first notify a user and then begin a conversation at a predetermined state in the dialog flow.

How Event-Driven Conversations Work

Users don’t need to have had a prior conversation with the skill that’s invoked by the external app. They can get a notification regardless of whether they’ve already had a chat. They can also get a notification while they’re currently engaged in a conversation with another skill, one that’s not the focus of the notification. When users get a notification while they’re in mid-conversation with another skill, it asks them if they want to switch conversations to take action on the notification.

If users answer “Yes” (which often means switching between skills):
  • Users are placed at the state in the dialog flow that starts them on the “notification flow”.

  • After they complete this flow, the digital assistant asks them if they want resume the prior conversation. If they answer yes, they’re returned to the point where they left off.

If users answer “No”:
  • They’ll continue with their current skill.

  • When they’ve finished the transaction, the digital assistant prompts them to take action on the notification.

Use Case: An Expense Reporting App

To get an idea of the initial user notification and following event-specific actions, consider an ODA that reacts to events sent by an expense reporting app that tracks the status of an expense report as approved, rejected, or more information required.

Depending on the event in question (approve, reject, or more information required), this app can invoke one of the ODA’s skills at a specific state that starts users on the path that’s specific to the notification: confirm that they’ve seen the approval, resubmit the expense report, or complete the expense report by adding missing information.

AIC Configuration

You enable AIC by configuring the skill, the digital assistant it belongs to, and by adding specific parameters to the payload of the external app’s event message.

Configure the Skill

  1. Add the payload-to-state mapping by clicking Settings (This is an image of the Settings icon. ) then Events. The payload is a key, one that identifies the start state in the dialog flow to the external application. You provide the payload name to the external app rather than the actual state name because it’s a constant; the name of the state can change when the dialog definition gets revised.

  2. Configure the dialog flow (optional):
    • Add start states that output the initial message that orients users to the skill bot or task at hand. When there are no expected actions expected from the user, this state can output a simple message (through a System.Outputcomponent, for example), or it can include (preferably numbered) options when further actions are needed.

    • Because AIC is only supported through the Twilio/SMS channel, you can make user input in this text-only channel less error-prone by configuring autonumbering in the skill bot’s dialog flow and by augmenting the flow’s output components with footers.

      The default configuration for Enable auto numbering on cards enforces auto-numbering on cards and lists for all of the skill bots that are registered to the ODA that are routed to the Twilio/SMS channel.

Configure the Digital Assistant

  1. Configure a Twilio/SMS channel (accessed by first clicking Channels in the left menu, selecting Users, and then clicking Add Channel).

  2. Route the Twilio channel to the skill used by the external app.
  3. Configure an application channel (Channels > Applications > Add Application Configuration). This is the channel through which the messages from the external app are sent to the skill bot. Like the other channels that you configure for the digital assistant, this channel generates a secret key. In this case, the external app uses this key to authenticate its POST requests.

    Creation of the application channel also generates the Inbound Application URL, which you provide to the external application to allow it to send messages.

  4. Add the Inbound Application URL (an optional property). This URL is generated by the creation of the application channel, so you can paste this value from the application channel configuration page. Adding this URL sends error messages to the external application that relate to problems with switching to the Twilio channel named in the message payload.

  5. Register the skill bot with the digital assistant. After you’ve added the skill bot, you can see its payload-to state mappings in the Events page (accessed through Settings).

  6. If needed, adjust the settings for Notification interrupt prompt and Enable auto numbering on cards in the Configuration page.

Configure the External App

  • Add the secret key that’s generated when you create the application channel. The application uses this key to sign the message.

  • Add the inbound URL that allows the external app to send notifications to the registered skill.

  • Include these properties in the message payload:
    • userId—The actual phone number of the user. This is one of the numbers that are associated with the phone number that’s both assigned to the Twilio account and used by the Twilio channel configuration.
    • payloadType—The name of the payload that’s mapped to the initialization state in the dialog flow.
    • skillName—The name (identifier) of the digital assistant or the name of the skill that's registered to the digital assistant and the recipient of the application event message payload.
    • channelName—The name of the Twilio Channel that’s configured for the digital assistant. The channel configuration uses the number assigned to the Twilio account. For the System test channel, you need to define userID with the system-generated ID and channelName with the name of the System test channel.
    • variables—The values that get passed to the dialog flow’s context variables. If the corresponding context variables have been defined in the dialog flow, then they will be populated with the corresponding values passed from the application event message payload.
        "userId": "+14255555000",
        "messagePayload": {
            "type": "application",
            "payloadType": "accountType",
            "skillName": "FinancialBot",
            "channelName": "MyTwilioChannel",
            "variables": {
                "accountType": "checking",
                "txnType": "credits"

Receive Notifications Through the System Test Channel

You can test out your AIC implementation using the Skill Tester (The Tester icon.). To do this, you need to include the system-generated ID and the name of the System test channel in the external app's payload, as illustrated by 7367764 and System_Global_Test in the following snippet:
    "userId": "7367764",
    "messagePayload": {
        "type": "application",
        "payloadType": "balance",
        "skillName": "DemoFinancialBot",
        "channelName": "System_Global_Test",
        "variables": {
        	"accountType": "checking",
        	"txnType": "credits"
Define the System Channel Name and System ID

To find the System test channel (System_Bot_Test or System_Global_Test) name for the channelName field, first click Channels in the left menu then select System.

The HTTP responses to the Skill Tester (The Tester icon.) holds the ID that you need for the userId definition in the payload. To view this response and obtain the ID from it, you need to use the Skill Tester in conjunction with your web browser's network development tool. These steps use Network Monitor from the Firefox Developer Toolbox as an example.
  1. Click The Tester icon. in the left navbar.
  2. Open Network Monitor by first selecting Web Developer in the browser menu, then click Network.
  3. Select XHR to display only REST requests.
  4. Enter a message in the Skill Tester.
  5. In the Network Monitor, select the skill's response and then open the Response tab.
  6. Enter userId in the Filter Properties field.
  7. Copy the userId value to the external app's payload.