22 Application-Initiated Conversations

In cases where you want to initiate a chat with your customers, you can use the application-initiated conversation (AIC) feature in Oracle Digital Assistant to start Twilio/SMS conversations with users. For example, you can use AIC to send an appointment reminder, a traffic alert, or flight status.

Application-initiated conversations are conversations that Digital Assistant initiates in response to an event it receives from an external app. Digital Assistant uses the contents of the app's event message to trigger one of its skills to first notify a user and then begin a conversation at the state in the dialog flow that's applicable to the event.

Use Case: An Expense Reporting App

To get an idea of the initial user notification and the subsequent event-specific actions, consider a Digital Assistant that reacts to events that are sent by an expense reporting app. This app will send messages whenever an expense report is approved or rejected and when more information is required.

You can create a skill that has start states for each of the events (approve, reject, and more information required). The start state can output a message about the event and then begin a flow that enables the user to take the applicable action:

  • Confirm that they’ve seen the approval
  • Resubmit the expense report
  • Complete the expense report by adding missing information

How Application-Initiated 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 also can 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.

AIC Configuration

You enable AIC by configuring a skill, a user channel, an application channel, and an external app. Optionally, you can add the skill to a digital assistant and configure the digital assistant for the AIC features in the skill.

Configure the Skill

You need to configure the skill to handle all the events that the external app can send to the skill.

For each event, do the following steps:

  1. If your external app will include a variables object in the message payload, then add context variables to hold the values of the object's properties.

    The context variable name must match the property name in the variables object. Say, for example, that the external app will send a request body like this for an appointment-reminder event:

    {
        "userId": "16035550100",
        "messagePayload": {
            "type": "application",
            "payloadType": "msgReminder",
            "channelName": "AppointmentUserChannel",
            "variables": {
            	"patientName": "Joe Doe",
            	"appointmentTime": "5:00 pm"
            }
        }
    }

    You'll need to add these equivalently-named context variables:

    context:
      variables:
        patientName: "string"
        appointmentTime: "string"  
  2. Ensure that your dialog flow has a start state for the event.

    Here's an example of the start state for an appointment-reminder event:

      remindermessage:
        component: "System.Output"
        properties:
          text: "Hi ${patientName.value}, your next appointment is scheduled for ${appointmentTime.value}. Please reply to this message to confirm, cancel, or postpone your appointment."
        transitions:
          return: "done"

    Tip:

    Because Twilio/SMS is a text-only channel, consider making user input less error-prone by configuring autonumbering in the skill’s dialog flow. If you add your skill to a digital assistant, then you can adjust the settings for Enable Auto Numbering on Postback Actions in the digital assistant's Configuration page. By default, this is set to ${(system.message.channelConversation.channelType=='twilio')?then('true','false')}
  3. To map the event to the start state, click Settings Settings icon, click Events, and click + Add Mapping. Then enter these fields:

    • Payload type: A name that identifies the event. The external app will use this name to direct the message to the applicable state.

      You use the payload type in the external app rather than the actual state name because it’s a constant; the name of the state might change if the dialog definition is revised.

    • State name: The start state for the event in the dialog flow.

    When you add a skill to a digital assistant, the skill's event-to-state mappings are added to the digital assistant's Events page automatically. You access this page from the digital assistant's Settings page.

Create a Twilio SMS User Channel

You need a user channel to link your skill with your Twilio account. Here are the basic steps for creating the channel. For information about getting a Twilio account and obtaining the necessary information, see Twilio/SMS.

  1. From the left navbar, click Channels, and then click Users.

  2. Click + Channel.

  3. In the Create Channel dialog:

    • Enter a name, and then choose Twilio SMS from the Channel Type drop-down list.

    • Enter the Twilio account SID, Auth token, and assigned phone number.

  4. Click Create.

  5. Note the webhook URL. You’ll need this to configure Twilio.

  6. Switch Channel Enabled to On.

  7. In the Route To drop-down list, select the skill or digital assistant that you want to associate with the channel.

    Note that if you select a skill from this list, then all external app messages that are sent to this channel are routed to the selected skill. However, if you select a digital assistant, then you'll need to specify the target skill in the external app's message payload.

  8. Go to your Twilio Console, click Phone Numbers Phone Numbers icon, and then click Active Numbers.

  9. Click the Twilio number in the Active Numbers page.

  10. In the Messaging Section of the Configure page, paste the webhook URL into the A Message Comes In field.

  11. Click Save.

Create a Channel for the External App

You need to create an application channel to allow the external app to send messages to Digital Assistant.

  1. From the left navbar, click Channels, click Applications, and then click + Application Configuration.

  2. Enter a name and optionally enter a description.

  3. (Optional) All channel-related error messages are logged to the server log file. If you also want Digital Assistant to send these error messages to an external web service, enter the web service's URL in the Outbound Application URL field.

    If an error occurs, such as a problem with initiating a conversation through the Twilio/SMS user channel, then Digital Assistant will send an error message as a JSON object with the botId, sessionId, and message properties.

  4. (Optional) If the targeted skill requires authentication using the System.OAuth2AccountLink component, and your external app will send the authenticated user ID instead of the Twilio/SMS user channel ID, then switch Use Authenticated User ID to On.

    When this is switched on, Digital Assistant will look up the authenticated user's Twilio/SMS user channel ID from the authentication service that's associated with the skill. Note that the user must have signed in through the skill for the look up to complete successfully.

  5. Click Create.

  6. Switch Application Enabled to On.

  7. Make a note of the secret key and inbound URL. These will be used by the external app.

    • It sends messages by sending POST request to the inbound URL.
    • It uses the secret key to authenticate its POST requests.

Configure the Digital Assistant

If you add your AIC-skill to a digital assistant, you might want to adjust these configuration parameters in the digital assistant's Settings Settings icon page:

  • Interrupt Prompt: This prompt is displayed when interrupting a flow to start a new flow.
  • Enable Auto Numbering on Postback Actions: Because Twilio/SMS is a text-only channel, check this setting to ensure that it's set to true for all Twilio channels so that the user input is less error-prone. By default, this setting is true for all Twilio channels: ${(system.message.channelConversation.channelType=='twilio')?then('true','false')}

Configure the External App

  • Include these properties in the message payload:

    • userId: This must be one of the following IDs:

      • Twilio/SMS Channel ID: The user's mobile phone number. This must be one of the numbers that are associated with the Twilio account's phone number that's specified in the Digital Assistant user-channel configuration.
      • System-Generated User ID: If you are testing your skill from the Skill Tester, then this must be the system-generated user ID for the session in the Skill Tester. See Testing AIC Skills in the Skill Tester.
      • Authenticated User ID: If the associated Digital Assistant application channel has Use Authenticated User ID switched to On, then this must be the authenticated user ID. The user with this authenticated user ID must already be signed in to the targeted skill through the System.OAuth2AccountLink component.
    • payloadType: The name of the event (payload type) that’s mapped to the start state in the dialog flow.

    • skillName and version: If the recipient of the message payload is a digital assistant, then include the skill's skillName and version to enable Oracle Digital Assistant to determine which skill bot and version to send the payload to.

    • channelName: The name of the Twilio user channel that’s configured for the skill or digital assistant. The channel configuration uses the phone number that's assigned to the Twilio account.

      If you are testing your skill from the Skill Tester, then you need to set channelName to the name of the System channel. See Testing AIC Skills in the Skill Tester.

    • 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 message payload.

    Here's an example:

    {
        "userId": "16035550100",
        "messagePayload": {
            "type": "application",
            "payloadType": "msgReminder",
            "channelName": "AppointmentUserChannel",
            "variables": {
            	"patientName": "Joe Doe",
            	"appointmentTime": "5:00 pm"
            }
        }
    }
  • To authenticate the request, add an X-Hub-Signature header with a SHA256 hash of the application channel's secret key. For example:

    X-Hub-Signature: sha256={{hash-secret-key}}
  • Send the POST request to the application channel's inbound URL. For example:

    POST http://<host>:<port>/connectors/v1/tenants/chatbot-tenant/listeners/application/channels/4E09-42F7-ECB7A7F18F62

Testing AIC Skills in the Skill Tester

You can use the Skill Tester The Tester icon. to test your AIC implementation. To do this, you need to get the System channel name and a Skill Tester's user ID, and then configure the external app to send messages to that channel and user.

Get the System Channel Name and Skill Tester User ID

You'll need the System channel name and the Skill Tester's user ID to send your external app's messages to the Skill Tester. When an external app sends a message to the System channel, Oracle Digital Assistant routes the message to the Skill Tester that has the specified user ID.

  1. To get the name of the System channel, from the left navbar, click Channels, click System, and then look at the name.

    The name will be either System_Bot_Test or System_Global_Test.

  2. To get the Skill Tester's user ID, open the skill and click Skill Tester Tester icon.
  3. Open Network Monitor by first selecting Web Developer in the browser menu, and then click Network.

  4. Select XHR to display only REST requests.

  5. Enter a message in the Skill Tester.

  6. After the skill outputs some text, go to the the Network Monitor, and then look at the Response tab.

    Select each response until you find one that contains a messagePayload.

  7. Enter userId in the Filter Properties field to display the value for the userId.

  8. Leave the Skill Tester active and don't click Reset.

    If you reset or close the Skill Tester then the user ID changes.

Send a Notification to the Skill Tester

After you get the name of the System channel and the system's user ID, you can send messages from your external app to the skill's tester.

To use the Skill Tester instead of Twilio/SMS, set userId to the system's user ID and set channelName to the name of the System channel, as shown here:

{
    "userId": "7319408",
    "messagePayload": {
        "type": "application",
        "payloadType": "msgReminder",
        "channelName": "System_Global_Test",
        "variables": {
        	"patientName": "Joe Doe",
        	"appointmentTime": "5:00 pm"
        }
    }
}