Oracle by Example brandingPass Customer Information to a Live Chat

section 0Before You Begin

This 30-minute tutorial shows you how to pass chat customer information from an Oracle Digital Assistant skill to Oracle Service Cloud.

This is the second tutorial in a series. Read the tutorials in this order:


When you transfer a skill's chat session to Oracle Service Cloud, there are several ways to pass contextual information with the transfer:

  • Conversation History: When insights is enabled for the skill, the skill passes the whole chat history to Oracle Service Cloud automatically. When you tested your skill in the first tutorial of this series, you saw the chat conversation history after you accepted an incoming request.
  • Chat Customer Information: Skills can pass the following chat customer information to Oracle Service Cloud.
    • E-mail address
    • First name
    • Last name
    • Contact
    • Organization
    • Category
    • Product
  • Incident Custom Fields: You can pass values for any Oracle Service Cloud custom field of type Incident.

You'll learn how to pass chat customer information in this tutorial, and you'll learn how to pass Incident custom fields in the next tutorial in this series.

Here’s the scenario for this tutorial:

You are a developer for a pizza restaurant that has an Oracle Digital Assistant skill on its web site that lets people order pizzas through natural conversation. If someone can't complete the order successfully or has questions that the skill can't handle, then the person can ask to speak to a human and the skill transfers the conversation to an Oracle Service Cloud live chat.

To put the transferred chat session in better context for the agent, you want to enhance the skill to pass the skill's category to the agent.

Here's what you'll need to do:

  • Learn the structure of the Oracle Service Cloud chat customer information fields.
  • Use cURL to get the category valid values from Oracle Service Cloud.
  • Add the category object to a map variable in the skill's dialog flow.
  • Pass the map variable from the System.AgentInitiation state in the dialog flow.
  • Test the skill and view the passed information in the live chat UI.

This tutorial guides you through these steps.

What Do You Need?

Before you can start this tutorial, you must first complete Integrate a Skill with Oracle Service Cloud Live Chat, which is the first tutorial in this series. You'll enhance the skill that you built during that tutorial.

Also, in this tutorial, you'll use cURL to access an Oracle Service Cloud REST API. If you haven't done so already, install cURL on your local system. See After you install cURL, set the cURL environment variable, CURL_CA_BUNDLE, to the location of your local CA certificate bundle. For information about CA certificate verification using cURL, see

As with the first tutorial, you also need:

  • Access to Oracle Digital Assistant 20.01 or later. If you are using an earlier version, then see The Legacy customerInformation Object in Using Oracle Digital Assistant to learn how to pass customer information.
  • Access to Oracle Service Cloud release 19A or later with Chat enabled and with the following chat configuration settings set to true:
    • Chat Custom Interface API (CHAT_CONSUMER_WS_API_ENABLED)
    • Chat Third Party Queue Integration API (CHAT_UQ_WS_API_ENABLED)

    Contact your Oracle account manager to set these configurations.

    If you are using a version earlier than 19A, see The Legacy customerInformation Object in Using Oracle Digital Assistant to learn how to pass customer information.

  • A chat-enabled Oracle Service Cloud interface, preferably one that is for development or testing, and not for production. You can use the Oracle Service Cloud Configuration Assistant, which you access from My Services, to verify that the interface is enabled for chat.
  • An Oracle Service Cloud staff account with the following profile permissions. Ask a Service Cloud administrator for assistance.
    • Account Authentication for Agent Browser User Interface
    • Account Authentication and Session Authentication for Public SOAP API
    • Agent access to the default chat queue
    • Available - Unrestricted chat agent status
  • Oracle Service Cloud chat-rules configuration that routes the conversations that are transferred from the skill to a queue that will be directed to your staff account. Ask a Service Cloud administrator for assistance.

section 1Learn the Structure of the Chat Customer Information Fields

Starting with Oracle Digital Assistant version 20.01 in combination with Oracle Service Cloud 19A, the skill uses Oracle Service Cloud REST APIs to pass information to Service Cloud Chat, and thus the format for passing data has changed. To pass customer information, you add the customerInformation object with the desired properties from the example shown below to the customProperties property in the System.AgentInitiation component.

  incidentID: 12345
    id: 12345
    id: 12345
    id: 12345
    id: 12345

Although you can also include the eMailAdress, firstName, and lastName properties in this object, there's no need to do so because the skill automatically sets those values from the corresponding profile properties.

section 2Get the Valid Values for Customer Information Fields

Later in this tutorial, you'll modify the dialog flow to pass in the category ID, and you'll need to know which values are valid for your Oracle Service Cloud instance. You can get the valid values for your instance's categories through the Oracle Service Cloud REST API.

To use cURL to get the valid values:

  1. In the fields below, enter the site name and domain name of your Oracle Service Cloud instance. For example, if the URL to your Oracle Service Cloud instance is, then the site name is sitename and the domain name is If your instance has multiple interfaces, then you must include the interface ID in the site name . For example, for the interface that has an ID of 2, you would use something like

  2. If necessary, such as if you are behind a firewall, get the host and port for the HTTPS proxy. For example: host.domain:80.
  3. In a terminal window, use one of the following cURL commands to get the valid values.

    • Without a proxy: Remember to replace <YOUR-USER-NAME> and <YOUR-PASSWORD> before you send the command.
      curl --request GET  --user "<YOUR-USER-NAME>:<YOUR-PASSWORD>" --header "osvc-crest-application-context: 1" https://./services/rest/connect/latest/serviceCategories
    • With a proxy: Remember to replace <YOUR-PROXY>, <YOUR-USER-NAME>, and <YOUR-PASSWORD> before you send the command.
      curl -x <YOUR-PROXY> --request GET  --user "<YOUR-USER-NAME>:<YOUR-PASSWORD>" --header "osvc-crest-application-context: 1" https://./services/rest/connect/latest/serviceCategories

    You can omit :<YOUR-PASSWORD> if you would rather be prompted for the password.

    The output will look similar to this:


    Here's an example of a category object from a formated version of the response:


section 3Add Customer Information to the Skill's Dialog Flow

The skill uses the profile values to populate and send the following chat customer fields automatically, you don't need to do anything to set these values:

  • E-mail address
  • First name
  • Last name

The skill also populates the question field automatically.

You'll enhance the dialog flow to set and pass the category ID.

As mentioned in What Do You Need, chat must be enabled for the interface. You can use the Oracle Service Cloud Configuration Assistant, which you access from My Services, to verify that the interface is enabled for chat.

  1. From Oracle Digital Assistant, open the skill that you created in the first tutorial in this series, and go to the dialog flow.
  2. Add a liveChatInfo context variable of type map to hold the customer information.
        size: "PizzaSize"
        type: "PizzaType"
        crust: "PizzaCrust"
        iResult: "nlpresult"
        liveChatInfo: "map"
  3. Find the setupProfileEmail state, add the following state after it, and then set the id property to a valid category ID:
        component: "System.SetVariable"
          variable: "liveChatInfo"
                id: 61 #Set this property
          next: "agentInitiation"
  4. In the setupProfileEmail state, change the next transition to "setupLiveChatInfo".
        component: "System.SetVariable"
          value: "" #Set this property
          variable: ""
          next: "setupLiveChatInfo"
  5. In the agentInitiation state, add a customProperties property and set it to "${liveChatInfo.value}" as shown here:
        component: "System.AgentInitiation"
          agentChannel: "ServiceCloudIntegration" #Set this property
          nlpResultVariable: "iResult"
          waitingMessage: "Let me connect you with a customer service agent who can further assist you."
          resumedMessage: "Please wait, someone will be with you shortly."
          customProperties: "${liveChatInfo.value}"
            accepted: "agentConversation"
            rejected: "reject"
            error: "agentSystemError"
    You can see the complete dialog flow in dialog-flow.txt.
  6. Click Validate to make sure that your dialog flow doesn't have syntax errors.

section 4Test Your Changes

Let's test receiving the skill's chat sessions with the newly added chat customer information.

Note that typically you'll see the customer information in the chat console, but it depends on how the Interaction Browser and Incident Browser workspaces are configured for your instance. Check with your administrator if you don't see the fields described in the steps below.

  1. In a browser, go to the Oracle Service Cloud Agent Browser UI (BUI), and sign in with the user name and password for the staff account described in What Do You Need?.

    The URL for the Agent Browser UI is typically:

  2. If you aren't signed into the chat, click Chat Logon Chat Logon.
  3. Set your status to one that enables you to receive chats (for example, unrestricted). If you see the Request a chat Chat Logon button, click it. (Your profile determines if you need to request a chat or chats appear in your queue automatically.)

    You are ready to accept the chat.

    Agent Browser UI showing the message you requested a chat
  4. Resize your browser windows such that you can see Digital Assistant and the Agent Browser UI and side-by-side.
  5. In the Digital Assistant UI, click Channels in the left navbar, click Agent Integrations, and verify that the Agent Integration channel for the Service Cloud interface is enabled.
  6. Go back to the skill.
  7. If the Train button doesn't show a check mark next to it, click Train and train the skill.
  8. Click Skill Tester Skill Tester, and then enter this text in the message field.
    I need to chat with a human
  9. In the Agent Browser UI, accept the incoming chat.
  10. Click the tab for the incident, as shown here:

    screenshot showing the incident tab

    The category field should show the name of the category that you passed in.

    screenshot showing category field
  11. To terminate the live chat, click Terminate the chat sessionTerminate the chat session.
  12. In the skill tester, click Reset, and then close the tester.

Congratulations! You've completed this tutorial.

next stepNext Tutorial

Transfer a Chat Session to a Live Chat Queue