An application-initiated conversation begins when an external app sends an event to the skill or to the digital assistant that it belongs to. There are a few changes that you need to make to your skill so that the conversation begins in the right place and displays the desired values.

An event that is sent from an external app must include a payload type, which uniquely identifies the event to the skill. Typically, the payload type indicates what the skill is supposed to do, such as msgReminder or cancelAppointment. The event can also include parameters in its variables JSON object, such as a patient's name or an appointment time.

In your skill, you must insure that there's a start state in the dialog flow for every event (multiple events can have the same start state). You also need to add context variables to hold the parameter values, if any. Then, you need to map the event's payload type to the start state.

For each event, do the following steps:

1. If your external app will pass a variables object in the event's 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:

   If the messaging platform is text-only, consider making user input less error-prone by configuring autonumbering in the skill’s dialog flow. Also consider showing or hiding text based on the messaging platform. See Text-Only Channels.

3. To map the event to the start state, click Settings , click Events, and click + Add Mapping. Then enter these fields:

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

     You use the payload type from the external app rather than the actual state name because payload type is a constant, whereas the name of the state could change if the dialog flow is revised.

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

   In this screenshot, the msgReminder payload type maps to the remindermessage state 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.

If your skill requires users to authenticate with Oracle Identity Cloud Service or Oracle Access Manager, then you must configure the application channel, skill, and external app to enable the skill to associate the authenticated user ID with the bot user ID.

For events that are sent to a user-authenticated skill to work, the user must have already signed into the identity provider from the skill. For example, let's say that Deva is using a skill to create an expense report. Before she can do anything in the skill, the skill asks her to sign in. The skill then associates her authenticated user ID with her user ID for the messaging platform and the messaging platform parameters that are cached in the user's profile.

After she completes her report, she asks to be notified when the expense is approved. Her company uses an external app to send the notification event to the same skill. In order for the app to send the event to a user-authenticated skill, it must send Deva's authenticated user ID instead of the messaging platform's user ID. Given the authenticated user ID, the skill can look up platform's user ID and the information from the cached profile that it obtained when Deva originally signed in.

If Deva never signed in from the skill, her authentication expired, or the profile cache expired, then Digital Assistant responds to the event request with a 500 error.

In addition to the steps in Configure the Skill, you must complete the following steps to configure application-initiated conversations for user-authenticated skills:

1. If your skill has already enabled user authentication, go to Settings > Authentication Services, open the service and ensure that the Refresh Token Retention Period is set to 14 days, which matches the user profile cache expiry duration. These values must be synchronized.

2. If your skill hasn't enabled user authentication yet, complete these steps:

   1. Ensure that an administrator has completed the steps in Identity Provider Registration.

   2. Create an authentication service for the identity provider as described in Authentication Services.

   3. Ensure that the authentication service's Refresh Token Retention Period is set to 14 days, which matches the user profile cache expiry duration. These values must be synchronized.

   4. To enable users to sign in from the skill, add a state for the System.OAuth2AccountLink component to the dialog flow as described in System.OAuth2AccountLink.

3. When you create the application channel, switch Use Authenticated User ID to On. Or, if it's already created, open the channel and switch it to On.

In the request body that your external app sends to Digital Assistant, remember to set the userId property to the authenticated user ID as described in Configure the External App.

For application-initiated conversations to work, you'll need to create a user channel to link the skill with your messaging platform account. See these topics for the steps to create a user channel for the specific platform.

• Twilio/SMS
• Slack
• Microsoft Teams

Note that if you select a skill from the channel's Route to 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.

You need to create an application channel to allow the external app to send messages to Digital Assistant. After you create the channel, Digital Assistant assigns a secret key. You need to use this secret key in your external app.

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 user channel, then Digital Assistant sends 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 messaging platform's user ID, then switch Use Authenticated User ID to On.

   When this is switched on, Digital Assistant will look up the messaging platform's user ID for the specified authenticated user ID. Note that the user must have signed in through the skill for the look up to complete successfully. For further details, see Configure a User-Authenticated Skill.

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.

If your skill supports application-initiated conversations and you add it to a digital assistant, you might want to adjust these configuration parameters in the digital assistant's Settings page:

• Interrupt Prompt: This prompt is displayed when interrupting a flow to start a new flow.
• Enable Auto Numbering on Postback Actions: It's good practice to make sure that this setting is true for all text-only channels so that the user input is less error-prone. By default, this setting is true for all Twilio channels: ${(system.channelType=='twilio')?then('true','false')}

The external app initiates an event by sending a POST request to an application channel's inbound URL. Here are the things the app must do to prepare and send the request.

• Include these properties in the request body (examples follow):

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

    • Microsoft Bot User ID: The bot user ID for the Microsoft Bot channel. This ID is specific to each Microsoft Bot channel. The skill saves this value in the profile.msBotUserId context variable.

    • Slack User ID: The Slack user's member ID. The skill saves this value in system.message.channelConversation.userId.

    • 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. The skill saves this value in the profile.firstName context variable.

    • System-Generated User ID: If you are testing your skill from Preview, then this must be the system-generated user ID for the session in Preview. See Testing Application-Initiated Conversations from Preview.

    • Authenticated User ID: If the associated 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. See Configure a User-Authenticated Skill.

  • messagePayload: This object contains:

    • type: Set this to application.

    • payloadType: The name of the event (payload type) that’s mapped to the desired start state in the dialog flow. See Configure the Skill.

    • skillName and version: (Optional) If the messaging platform's user channel routes to a digital assistant, then you must include the skill's skillName and version so that the digital assistant knows which skill and version to send the event to.

    • channelName: The name of the messaging platform's user channel that’s configured for the skill or digital assistant.

      If you are testing your skill from Preview, then you need to set channelName to the name of the System channel. See Testing Application-Initiated Conversations from Preview.

    • variables: (Optional) Key-value pairs to pass to the dialog flow’s context variables. If the corresponding context variables are defined in the dialog flow, then they're populated with the values passed from this object.

  • channelProperties: This object is for MS Teams and Slack. You don't need to include this object in the request body if Use Authenticated User ID is switched on for the user channel.

    MS Teams channelProperties Object

    This object is required if the user hasn't interacted with the conversation within 14 days. Its properties are:

    • botName: This is the bot handle that you specified when you created the bot channel registration as described in Step 1: Create a Bot. This value is saved in the profile.botName context variable.

    • tenantId: The ID of the Microsoft Teams tenant. This value is saved in the profile.tenantId context variable.

    • serviceUrl: The service URL for the bot. This value is saved in the profile.serviceUrl context variable.

    When the Microsoft Teams user converses with the skill, Digital Assistant captures and stores these values in the profile cache. If an event's request payload doesn't include the channelProperties object, then the skill will use the values from the profile cache, if available (the cache expires after 14 days). The skill uses the cached profile values only if they are missing from the request body.

    When your dialog flow sends a request for notification to the backend, such as through a custom component, it should pass those profile values to the backend. The external app can then use those values in the channelProperties object in the case where the profile cache might have expired. Here's a snippet of custom component code that gets the values to send to the back end.

        let serviceUrl = conversation.variable('profile.serviceUrl') ?
            conversation.variable('profile.serviceUrl') : "";
        let tenantId = conversation.variable('profile.tenantId') ? 
            conversation.variable('profile.tenantId') : "";
        let botName = conversation.variable('profile.botName') ?
            conversation.variable('profile.botName') : "";
        let msBotUserId = conversation.variable('profile.msBotUserId') ?       
            conversation.variable('profile.msBotUserId') : "";

    Slack channelProperties Object

    For Slack, include these properties in the channelProperties object:

    • teamId: Slack workspace ID. This value is saved in the profile.team_id context variable.

    • channel: ID of the channel in the workspace. That is, the user's channel. This value is saved in the profile.channel context variable.

    You can get the team ID and channel from the Slack web URL. For example, if the URL is https://app.slack.com/client/ABCDEFG/HIJKLMNOP, then the team ID is ABCDEFG, and the channel is HIJKLMNOP.

  Here are examples for the different messaging platforms for skills that don't use authenticated user IDs.

  Slack example:

  { 
      "userId": "ABCDE712A3",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          },
          "channelProperties": {
              "teamId": "ABCDEFG",
              "channel":"HIJKLMNOP" 
          } 
      }
  }

  MS Teams example:

  { 
      "userId": "12:1A2B3C3d....",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          },
          "channelProperties": {
              "tenantId": "ab12c34d-e56...",
              "botName":"my-bot",
              "serviceUrl":"https://example.com/path/"
          } 
      }
  }

  Twilio example:

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

  This example shows how to send an event to a channel that's routed to a digital assistant. When the channel routes to a digital assistant, you must include the skill name and version.

  {
      "userId": "1234567890",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "skillName": "myBot",
          "version": "1.0",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

  Here's an example for a user-authenticated skill (that is, the associated application channel has Use Authenticated User ID switched to On). This example applies to MS Teams, Slack, and Twilio. Note that for MS Teams and Slack, you don't include the channelProperties object when you route to a user-authenticated skill.

  {
      "userId": "first.last@example.com",
      "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 body using the application channel's secret key. For example:

  X-Hub-Signature: sha256={{HMAC SHA-256 signature of body}}

  The Use Postman as an External Application section in the Send Reminders Using Application-Initiated Conversations tutorial shows an example of setting this header.

• Send the POST request to the application channel's inbound URL. It should look something like this:

  POST https://<host>:<port>/connectors/v2/listeners/application/channels/4E09-42F7-ECB7A7F18F62

You'll need the System channel name and the Preview's user ID to send your external app's messages to the Preview. When an external app sends a message to the System channel, Oracle Digital Assistant routes the message to the Preview 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 Preview's user ID, open the skill and click Preview .

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

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 Preview active and don't click Reset.

   If you reset or close the Preview then the user ID changes.

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

To use the Preview instead of the messaging service, set userId to the Preview'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"
        }
    }
}