Oracle by Example brandingSend Reminders Using Application-Initiated Conversations

section 0Before You Begin

This 30-minute tutorial shows you how to use the application-initiated conversation (AIC) feature in Oracle Digital Assistant to start SMS conversations with users.

Background

The use case for this tutorial is a vision-care appointment reminder service. Vision Corp., a fictitious vision center, wants to reduce the number of patients that don't show up for their eye appointments by reminding them about their appointment a day or two in advance. The approach that Vision Corp. takes is outlined below.

  • A Vision Corp. appointment manager initiates a short message to be sent to patients that previously had their mobile number registered.
  • Patients receive a SMS notification informing them about their upcoming appointments.
  • Opening the SMS, patients can then respond to the automated message and confirm, decline, or postpone their appointment.

The solution consists of four main building blocks:

  • Twilio SMS: A short messaging service that sends user messages on behalf of Oracle Digital Assistant to initiate a user conversation.
  • Oracle Digital Assistant Skill: A skill that responds to dispatching requests from the application.
  • External Application: A custom application that uses an application channel in Oracle Digital Assistant to trigger user notifications. In this tutorial, the external application is simulated by Postman.
  • SMS client: The user's phone that receives the message and that becomes a messaging client for the skill.
Twilio, Oracle Digital Assistant, External Application, SMS client on user phone

What Do You Need?

  • Access to Oracle Digital Assistant.
  • Mobile phone (either a smart phone or a non-smart phone will work).
  • A Twilio account. If you don't have an account, this tutorial includes steps for obtaining a trial account.
  • Postman or an equivalent REST client. If you don't have either, this tutorial includes steps for installing Postman.

section 1 Set Up the Vision Corp. Skill

For this tutorial, a starter skill named Vision Corp is provided. You access the provided skill by following these steps:

  1. Open Oracle Digital Assistant in a browser.
  2. Click icon to open side menu on the top-left corner of the page to expand the side menu.
  3. Expand Development and select Skills.
  4. Click icon to open side menu again to hide the side menu.
  5. In the Skills dashboard, type vision corp in the Filter field to find the starter skill.

    If the Vision Corp skill isn’t available in your instance, then download vision-corp-1-0-starter.zip, click Import Skill, and import it into your instance.

  6. On the Vision Corp card, click Options Options, and then select Clone.
    Options menu on skill card
  7. Name the skill <your initials>_VisionCorp, or use any other prefix that creates a name that's unique to the instance.
    Create Clone dialog box with display name and name set to RD_VisionCorp
  8. Select Open cloned skill afterwards, and then click Clone.
  9. Ensure that Intents Intents is selected.
  10. Click the ConfirmAppointment intent and notice the utterances.
  11. Similarly observe the utterances for the other intents: CancelAppointment, RescheduleAppointment, and WelcomeMessage.
  12. Next, click Train button, which is in the top-right corner of the page.
  13. In the opened dialog, keep the default settings and click Submit.

    Wait a few seconds for the training to finish.

  14. To test the skill, click Skill Tester Skill Tester, which is located near the bottom of the left navigation bar.
  15. In the skill tester's Message field, type confirm the appointment and press Enter.
  16. Click Reset at the top of the tester window to clear the context and history.
  17. Next, try I want to cancel the appointment.
  18. Finally, try can you reschedule?
  19. Click Large X to close the tester window.

section 2Prepare Your Skill for an Application-Initiated Conversation

To enable application-initiated conversations in your skill, add a dialog-flow state to initiate the conversation, and then map a key value, which will be referenced by the external application, to this state.

  1. Click Flows Flows to open the dialog flow editor.
  2. Under variables: add these two context variables to hold the patient name and appointment time that will be sent by the external application: 
    
    patientName: "string"
    appointmentTime: "string"
    Tip: You can click the Copy icon Copy in the above code box to copy its content to your clipboard.

    Indentation is important. Ensure that the variables are indented the same as iResult as shown here.

    variables property with patientName, appointmentTime, and iResult at the same indentation

  3. To add a state to initiate the conversation, click + Components.
  4. Select the User Interface category.
  5. Select Output.
    Output selected in the User Interface category
  6. From the Insert After dropdown, select rescheduleappointment.
  7. Ensure the Remove Comments switch is ON.
  8. Click Apply.
  9. Change the state name of the newly added component from output to remindermessage.
  10. Edit the state to look like the following: 
    
  remindermessage:
    component: "System.Output"
    properties:
      text: "Hi ${patientName.value}, your next Vision Corp. appointment is scheduled for ${appointmentTime.value}. Please reply to this message to confirm, cancel appointment, or postpone appointment."
    transitions:
      return: "done"

    Your updated OBotML should look like this:

    Screenshot of the complete dialog flow
  11. Click Validate to ensure that there are no errors in your dialog flow.

    If you experience problems, you can copy the entire dialog flow code from the vision-corp-flow.txt file.

  12. The incoming message from the external application will contain a key. To map the key to the start state, which is remindermessage, click Settings Settings, and then click the Events tab.
    Screenshot of the Events tab with a + Add Mapping button.
  13. Click + Add Mapping to display the Payload type and State name fields.
    Screenshot of the + Add Mapping button, the Payload type field and the State name field.

  14. Set these values, and then press Enter:

    • Payload type: msgReminder
    • State name: remindermessage
    Screenshot of the Payload type field and the State name field set to the specified values.

    You provide the payload type from the external app rather than the actual start-state name because it’s a constant, whereas the name of the start state can change if the dialog definition is revised.

section 3Set Up Twilio

To use Twilio SMS as a channel you need to:

  • Sign up for a Twilio paid or trial account.
  • Obtain a Twilio number to use to configure an application channel.
  • Add a verified mobile number to use for a registered patient number.
  1. To create a Twilio trial account with your email ID, go to https://www.twilio.com/try-twilio.
    Screenshot of Twilio Get started with a free twilio account page.
  2. Enter the required information, and then click Get Started.
  3. When prompted, enter your mobile phone number (You need to have a verified phone number to get a Twilio number).

    A verification code is sent to your mobile phone. Enter this verification code to add your number as a verified phone number

    Screenshot of Twilio Verify Phone Number page.
  4. Click Skip to dashboard to move to the Twilio dashboard.
    Screenshot with skip to dashboard button.
  5. In the left navigation bar on the Twilio console, click #, click Getting Started, and then click Get your first Twilio phone number.
    Screenshot of Get Started with Phone Numbers page with Get your first Twilio phone number button.
  6. In the Your first Twilio Phone Number dialog box, click Choose this Number, or search for a different number. Any SMS-enabled number will do. We'll refer to this number as the skill's Twilio number.
    Screenshot with phone number, whether SMS enabled, search for a different number link, and choose this number button.

    Note: You should choose a United States phone number as it is the simplest one to get. Numbers from other countries often require additional proof of identity.

  7. Make a note of the number. You'll need the number to create a Twilio user channel in Oracle Digital Assistant.
  8. In the left navigation bar, click the home icon to open the Dashboard page, and then make a note of the account SID and AUTH token.

    You’ll need these values to create a Twilio user channel in Oracle Digital Assistant.

    Screenshot with account SID and AUTH token
  9. In the left navigation bar, click # to display the Phone Numbers page, and then click Verified Caller IDs.
  10. If your mobile number isn't on the list, click + to add a verified number that you can send messages and make calls to.
    Screenshot of Verify Caller IDs page with a + button, number field, and friendly name field.

    You'll use this number for the patient's registered mobile number.

section 4Set Up the Application Channel in Oracle Digital Assistant

In this section, you’ll configure the application channel that enables an external application to send notifications to the Vision Corp skill so that it can trigger a conversation with a patient.

  1. In Oracle Digital Assistant, click icon to open side menu, click Development, and then click Channels.
  2. Click the Applications tab.
    Screenshot of the users, agent integrations, applications, and system tabs on the channels page.
  3. Click + Application Configuration to enter details.
    Screenshot of the application configuration dialog box with name, description, outbound application URL, and use authenticated user id fields.
  4. Set the name to <your initials>_VisionCorp_ApplicationChannel.
  5. The Use Authenticated User ID switch is turned Off by default. Keep it this way and press Create.

    An unbound URL and a secret key are generated for the new application channel. External applications should use the inbound URL to send messages and should sign the message with the secret key.

    Note: The Outbound URL is optional. If provided, the skill may use this URL to send information about errors. This URL isn’t used in this tutorial.

  6. Set the Application Enabled switch to On to enable the channel.
  7. Make a note of the secret key and inbound URL. You'll use these values when you initiate the conversation from an external application, which is Postman in this tutorial.
    Screenshot of the configured application with the application enabled switch set to On and the secret key and inbound URL displayed.

section 5Set Up the User Channel in Oracle Digital Assistant

In this section, you’ll configure the application channel that will be used to send and receive messages via a Twilio SMS channel.

  1. In the Channels page, click the Users tab to create the Twilio user channel.

  2. Click + Channel and set these values:

    • Name: <your initials>_VisionCorpUserChannel
    • Channel Type: Twilio SMS
    • Account SID: Your Twilio account SID
    • Auth Token: Your Twilio Auth Token
    • Phone Number: Your Twilio number
    Screenshot of the Create Channel dialog box with the fields described in this step.
  3. Click Create.
  4. If the user channel that you just created isn't selected in the Users tab, find it and select it.
  5. In the Users tab, select your skill from the Route To dropdown list.
    Screenshot of the User tab with the new channel selected and the route to field highlighted.

    Note: You also can route channels to digital assistants that contain skills. To simplify this tutorial, we'll route to the skill.

  6. Set the Channel Enabled switch to On to enable the channel.
  7. Make a note of the webhook URL. You'll use this URL to configure Twilio messaging in the Twilio console in the next section.

section 6Configure Twilio Messaging in the Twilio Console

In this section, you’ll configure SMS messaging.

  1. Go to the Twilio dashboard at https://www.twilio.com/console, click All Products & Services All Products & Services, and then click # Phone Numbers.
  2. Click Active Numbers, and then select your Twilio number.
    Screenshot of the Active Numbers page.
  3. In the Configure tab, scroll down to the Messaging section and set the A MESSAGE COMES IN field to the webhook URL that you obtained when you created the Twilio SMS user channel in Oracle Digital Assistant.
    Screenshot of the Messaging section with the A Message Comes in field highlighted.
  4. Click Save.

    Oracle Digital Assistant can now communicate on the Twilio SMS user channel that you created.

section 7Test the Skill Using SMS

You are now ready to test the SMS-based Vision Corp skill using the validated caller (that is, the patient).

  1. Using the mobile phone that is emulating the patient, send an SMS with the following text to your active Twilio number: 
    Who are you?
  2. After a few seconds, you should receive the following response back:

    Sent from your Twilio trial account – Hi, I am the Vision Corp. appointment reminder bot!

    Congratulations! You've confirmed that the SMS channel is working and is routing the request to Vision Corp skill.

    If you don't get the response, verify that your user channel is enabled, you've provided the correct account SID and AUTH token, and that you used the user channel's Webhook URL for the Twilio messaging Webhook URL. Also verify that your application channel is enabled.

    If you don't get the response, verify that Channel Enabled is switch to On in the user channel.

section 8Use Postman as an External Application

Now you need to set up an SMS Reminder Management application, which sends reminders to the patients. Once a user receives the SMS notification, the user can reply back to confirm, reschedule, or cancel the appointment a using free-flowing text message.

Instead of building an external web app to initiate the conversation (which is not the focus of this tutorial), you'll use the Postman REST client to simulate the external app. Postman will send an appointment reminder to the Vision Corp skill in Oracle Digital Assistant, which then will send an SMS notification to the patient's mobile number. In order to achieve this, the external application needs to know the following information:

  • Inbound URL and secret from your application channel
  • Twilio SMS user-channel name
  • The verified phone number of the patient who'll receive the SMS
  • Skill's payload type, which is msgreminder in this tutorial
  • Skill name and version
  1. Install Postman from https://www.getpostman.com/downloads/.
  2. Download aic-postman-collection.json.
  3. To import the AIC HOL collection into Postman, click Import, and then drop or choose the aic-postman-collection.json file.
    Screenshot of the Import dialog, which says drop files here and has a choose files button.

    If you don't see the imported collection, click the Collections tab and then enter AIC HOL in the search field.

  4. Expand AIC HOL, and then select POST SMSReminderAppRequest.
    Screenshot of the Collections tab with AIC HOL expanded and POST SMSReminderAppRequest selected.
  5. Observe the URL, headers, body, and pre-request script.
    Screenshot of the POST SMSReminderAppRequest page.

    You now need to update the POST request based on your user and application channel configurations.

  6. In the URL field, replace PASTE_YOUR_APPLICATIONS_CHANNEL_INBOUND_URL_HERE with your application channel's inbound URL.

    You can find this by going to Development > Channels > Application > <your application channel>.

  7. Click the Pre-request Script tab and replace ENTER_YOUR_APPLICATION_CHANNEL_SECRET_KEY with your application channel's secret key.

    You can find this by going to Development > Channels > Application > <your application channel>.

    Screenshot of the Pre-request Script tab.

  8. Click the Body tab and replace the following values:

    • ENTER_PATIENT_MOBILE_NUMBER_HERE: The registered mobile number for the patient. Remember that this is the number that you validated in Twilio as Verified Caller ID (that is, the patient's mobile number).
    • ENTER_TWILIO_USER_CHANNEL: The name of your Twilio SMS user channel, which is something like <your_initials>_VisionCorpUserChannel.
    • ENTER_PATIENT_NAME: The name to use for the patient's name.
    Screenshot of the Body tab.
  9. Click Send, and then observe the Status value.
    Screenshot of the Body tab.
    • Status 202: Accepted indicates that the request was sent successfully for further processing. You'll get this status if you set up the POST request correctly.
    • Status 403: Forbidden indicates that access to the requested URL is forbidden. In this case, check if you've provided the correct secret key in the Pre-request Script tab.
    • Status 404: Not Found indicates that the POST URL might be incorrect. Ensure that you've provided the correct inbound URL. Also ensure that the application channel is enabled.
  10. After a successful POST is sent, you'll receive an SMS notification on the mobile phone for the patient's number. It will be something like: 
    Hi Joe Doe, your next Vision Corp. appointment is scheduled for 5:00 PM. 
Please reply to this message to confirm, cancel appointment, or postpone appointment.

  11. You can reply to this message to either confirm, postpone, or cancel. For example, you can enter one of the following messages:

    • Cancel it
    • I will come
    • Change the slot
    • Confirmed

    Based on the user input, the skill will either confirm, postpone, or cancel the appointment.

    Screenshot of the text messages described in this step and the preceding one.

    Tip: Twilio uses the following keywords for opting out of notifications, so don't respond with the single word cancel: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, or QUIT

more informationWant to Learn More?

See Application-Initiated Conversations in Using Oracle Digital Assistant.