Pass Customer Information to a Live Chat

When conversation logging is enabled for a skill, it passes the whole chat history to Oracle B2C Service automatically. In addition to the chat history, you also can send some specific customer information.

Incident ID
Chat Customer Information: Skills can pass the following chat customer information to Oracle B2C Service.
- E-mail address
- First Name
- Last Name
- Contact
- Organization
- Category
- Product
The skill uses the profile values to populate and send these chat customer fields automatically, you don't need to do anything to set these values:
- E-Mail address
- First Name
- Last Name
Incident Custom Fields: You can pass values for any Oracle B2C Service custom field of type Incident.

To learn about custom fields, see Overview of Custom Fields in Using Oracle B2C Service.

Note

If you are using an agent-integration channel that was created prior to 20.1, or your channel connects to a Oracle B2C Service instance that's earlier than 19A, you can also pass interface information. With channels that are created in version 20.1 and later and connect to Oracle B2C Service 19A and later, you include the interface ID in the channel's URL.

To send customer information to the live agent, you pass a map in the System.AgentInitiation component's customProperties property. Here's the top-level structure of the map:

incidentID: # type int
customerInformation: # chat customer information object
customFields: # incident custom fields object

The incidentID Property

You can pass an Incident ID to the live agent by adding an incidentID property to the customProperties map.

Here's an example:

context:
  variables:
    liveChatInfo: "map"
    customerTicketId: "int"
...
  setCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        incidentID: "${customerTicketId}" # long value
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

Tip:

If you want to associate a chat request with an existing incident, then you can create a custom component to retrieve the incidentId by sending a REST request like the following example. This REST request retrieves the most recent incident for the contact with a matching email address.

https://<URL>/services/rest/connect/latest/incidents?q=primaryContact.ParentContact.Emails.EmailList.Address like 'email@gmail.com'&orderBy=createdTime:desc&limit=1

The response body contains an href link, which contains the incident ID:

{
    "items": [
        {
            "id": 26302,
            "lookupName": "200116-000003",
            "createdTime": "2020-01-16T13:08:25.000Z",
            "updatedTime": "2020-01-16T20:25:21.000Z",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://<URL>/services/rest/connect/v1.4/incidents/26302"
                }
            ]
        }
    ],

To learn about custom components, see Backend Integration. To learn about the Oracle B2C Service REST APIs, see REST API for Oracle B2C Service.

The Standard customerInformation Object

This section discusses the customerInformation object for skills that use an agent-integration channel that was created in version 20.01 or later and that connects to Oracle B2C Service version 19A or later.

You can use the customerInformation object in the customProperties map to pass the following chat customer information:

incidentID: int.
eMailAddress: string. Maximum 80 characters. Your skill automatically sets this value from the corresponding .profile properties (described in Profile-Scope Variables for User Context) and passes it to Oracle B2C Service.
firstName: string. Maximum 80 characters. Your skill automatically sets this value from the corresponding .profile properties (described in Profile-Scope Variables for User Context) and passes it to Oracle B2C Service.
lastName: string. Maximum 80 characters. Your skill automatically sets this value from the corresponding .profile properties (described in Profile-Scope Variables for User Context) and passes it to Oracle B2C Service.
contactID: Pass a value of type int in the id sub-property.
organizationID: Pass a value of type int in the id sub-property.
productID: Pass a value of type int in the id sub-property.
categoryID: Pass a value of type int in the id sub-property.

This example sets the contactID.

context:
  variables:
    liveChatInfo: "map"
    contactId: "int"
...
  setCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        customerInformation:
          contactID:
            id: "${customerId}"
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

Tip:

You can use the Oracle B2C Service REST API to view the valid values for customer information fields. For example, this GET request lists the categories:

curl --request GET \
--url https://<sitename.domain>/services/rest/connect/latest/serviceCategories \
--header 'authorization: Basic <base64-encoded-username+:+password>' \
--header 'osvc-crest-application-context: <some-comment>'

The Legacy customerInformation Object

This section discusses the customerInformation object for skills that use an agent-integration channel that was created before 20.01 or a channel that connects to an Oracle B2C Service instance that's earlier than 19A.

You use the customerInformation object in the customProperties map to pass chat customer information, such as the Interface ID, Contact ID, or Category ID. The customerInformation object can contain the fields that are defined in the Chat Customer Information section in the Oracle B2C Service WSDL at http://<sitename.domain>/services/soap/connect/chat_soap?wsdl=server.

For objects, change the initial character in the name to lower case, and change the names of simple fields to all lower case.

If you don't pass the interfaceID object, the skill uses a default of id:{id: 1}. Note that if the interface isn't chat enabled, then the initiation handshake will fail. You can use the Oracle B2C Service Configuration Assistant, which you access from My Services, to verify if an interface is enabled for chat.

This example sets the interfaceID and contactID.

Tip:

Because the WSDL specifies that interfaceID is of type NamedID, we could've used name: "myInterfaceName" instead of id: id: "${interfaceId}".

context:
  variables:
    liveChatInfo: "map"
    interfaceId: "int"
    contactId: "int"
...
  setCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        customerInformation:
          interfaceID:
            id:
              id: "${interfaceId}"
          contactID:
            id: "${customerId}"
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

While you can define the EMailAddress, FirstName, and LastName fields that are described in the WSDL’s Chat Customer Information section, your skill automatically sets these values from the corresponding .profile properties (described in Profile-Scope Variables for User Context).

Tip:

You can use the Oracle B2C Service REST API to view the valid values for customer information fields. For example, this GET request lists interface IDs and names:

curl --request GET \
--url https://<sitename.domain>/services/rest/connect/latest/siteInterfaces \
--header 'authorization: Basic <base64-encoded-username+:+password>' \
--header 'osvc-crest-application-context: <some-comment>'

This GET request lists the categories:

curl --request GET \
--url https://<sitename.domain>/services/rest/connect/latest/serviceCategories \
--header 'authorization: Basic <base64-encoded-username+:+password>' \
--header 'osvc-crest-application-context: <some-comment>'

As mentioned earlier, the customerInformation map structure must conform to the Chat Customer Information structure that's shown in the WSDL at the following address:

http://<sitename.domain>/services/soap/connect/chat_soap?wsdl=server

Here's an excerpt from the WSDL:

<!--  ============================== -->
<!--    Chat Customer Information    -->
<!--  ============================== -->

<xs:complexType name="ChatCustomerInformation">
    <xs:sequence>
        <xs:element name="EMailAddress" minOccurs="0" maxOccurs="1">
            <xs:simpleType>
                <xs:restriction base="xs:string">
                    <xs:maxLength value="80"/>
                </xs:restriction>
            </xs:simpleType>
        </xs:element>

        <xs:element name="FirstName" minOccurs="0" maxOccurs="1">
            <xs:simpleType>
                <xs:restriction base="xs:string">
                    <xs:maxLength value="80"/>
                </xs:restriction>
            </xs:simpleType>
        </xs:element>

        <xs:element name="LastName" minOccurs="0" maxOccurs="1">
            <xs:simpleType>
                <xs:restriction base="xs:string">
                    <xs:maxLength value="80"/>
                </xs:restriction>
            </xs:simpleType>
        </xs:element>

        <xs:element name="InterfaceID" type="rnccm:NamedID" minOccurs="1" maxOccurs="1"/>
        <xs:element name="ContactID" type="rnccm:ID" minOccurs="0" maxOccurs="1" />
        <xs:element name="OrganizationID" type="rnccm:ID" minOccurs="0" maxOccurs="1" />
        <xs:element name="Question" type="xs:string" minOccurs="0" maxOccurs="1"/>
        <xs:element name="ProductID" type="rnccm:ID" minOccurs="0" maxOccurs="1"/>
        <xs:element name="CategoryID" type="rnccm:ID" minOccurs="0" maxOccurs="1"/>
    </xs:sequence>
</xs:complexType>

Some objects are of type rnccm:ID, which is defined in the next excerpt. Notice that the object contains an id field of type long.

<xs:element name="ID" type="ID"/>
<xs:complexType name="ID">
    <xs:attribute name="id" type="xs:long" use="optional"/>
</xs:complexType>

InterfaceID is of type rnccm:NamedID. Notice that this object can contain an ID (long), a Name (string), or both.

<xs:element name="NamedID" type="NamedID"/>
<xs:complexType name="NamedID">
    <xs:sequence>
        <xs:element name="ID" type="ID" minOccurs="0" maxOccurs="1"/>
        <xs:element name="Name" type="xs:string" minOccurs="0" maxOccurs="1"/>
    </xs:sequence>
</xs:complexType>

The casing differs between the WSDL and the customProperties map. In the map, the first letter for an object name is lower case (Pascal case). For example, ProductID in the WSDL would be productID for the map object. The simple field names are all lower case (Name becomes name, for example).

The Standard customFields Object

This section discusses the customerFields object for skills that use an agent-integration channel that was created in version 20.01 or later and that connects to Oracle B2C Service version 19A or later.

You use the customFields object in the customProperties map to pass values for any Oracle B2C Service custom field of type Incident.

The customFields object is an array of maps that contain the following properties.

Simple fields:
- name: The field's column name (lower case) preceded by c$.
- type: Allowable values are BOOLEAN, DATE, DATETIME, INTEGER, LONG, STRING, and DECIMAL.
- value: The field's value.
Menu field:
- name: The field's column name (lower case) preceded by c$.
- value: You can set the value to either the field's ID or the menu item's text. Notice that this object doesn't have a type property.
  
  Tip:
  To find the ID for a menu item, open the custom field's details page from the Oracle B2C Service desktop Service Console. Hover over a menu item and wait for several seconds. The tool tip will appear and show the ID for that item.

Here's an example:

context:
  variables:
    liveChatInfo: "map"
...
  setupCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        customFields:
          - name: "c$text_field"        # text field
            type: "STRING"
            value: "SILVER"
          - name: "c$text_area"         # text area
            type: "STRING"
            value: "My package arrived but there were no contents in the box. Just bubble wrap."
          - name: "c$integer"           # integer
            type: "INTEGER"
            value: 21
          - name: "c$yes_no"  # yes/no (1=yes and 0=no)
            type: "BOOLEAN"
            value: 1
          - name: "c$date_field"        # date (yyyy-MM-dd'T'00:00:00. Use 0 for time)
            type: "DATE"
            value: "2020-02-04T00:00:00+00:00" 
          - name: "c$date_time"         # datetime (yyyy-MM-dd'T'HH:mm:ssXXX)
            type: "DATETIME"
            value: "2020-02-04T21:24:18+00:00" 
          - name: "c$menu"              # menu (no type property, you can pass the string or the ID for the value property)
            value: "12"
    transitions:
      ...
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

Tip:

You can send the following GET request, which uses RightNow Object Query (ROQL), to obtain a list of the column names:

curl --request GET \
--url https://<site.domain>/services/rest/connect/latest/queryResults/?query=select%20CustomFields.c.*%20from%20Incidents \
--header 'authorization: Basic <base64-encoded-username+:+password>' \
--header 'osvc-crest-application-context: <some-comment>'

To get the valid values for a custom field, send a GET request that uses RightNow Object Query (ROQL) like this:

curl --request GET \
--url https://<site.domain>/services/rest/connect/latest/queryResults/?query=select%20CustomFields.c.skillType%20from%20Incidents%20where%20CustomFields.c.skillType%20IS%20NOT%20NULL \
--header 'authorization: Basic <base64-encoded-username+:+password>' \
--header 'osvc-crest-application-context: <some-comment>'

The Legacy customFields Object

You use the customFields object in the customProperties map to pass values for any Oracle B2C Service custom field of type Incident.

The customFields object is an array of maps that contain name, dataType, and dataValue properties, as shown in the following example. The name property's value is the field's lower-case column name preceded by c$.

context:
  variables:
    liveChatInfo: "map"
    skillType: "string"
...
  setupCustomFields:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        customerInformation: 
          interfaceID:
            id:
              id: 1     
        customFields:
# Text Field
          - name: "c$da_text_field"
            dataType: "STRING"
            dataValue:
              stringValue: "SILVER"
# Text Area
          - name: "c$da_text_area"
            dataType: "STRING"
            dataValue:
              stringValue: "This is a very long string that is more than 32 characters."
# Integer
          - name: "c$da_integer"
            dataType: "INTEGER"
            dataValue:
              integerValue: 21
# Menu
          - name: "c$da_menu"
            dataType: "NAMED_ID"
            dataValue: 
              namedIDValue:
                name: "Item 1"
# Instead of name, you can use
#                id:
#                  id: 1
#
# Yes/No
          - name: "c$da_is_from_skill"
            dataType: "BOOLEAN"
            dataValue:
              booleanValue: true
# Date (XML Schema Date)
          - name: "c$da_date"
            dataType: "DATE"
            dataValue:
              dateValue: "2019-10-26" 
# DateTime (XML Schema DateTime)
          - name: "c$da_datetime"
            dataType: "DATETIME"
            dataValue:
              dateTimeValue: "2019-10-26T21:32:52"               
    transitions:
      ...
  ...
  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      ...
      customProperties: "${liveChatInfo.value}"

Tip:

You can send the following GET request, which uses RightNow Object Query (ROQL), to obtain a list of the column names:

curl --request GET \
--url https://<site.domain>/services/rest/connect/latest/queryResults/?query=select%20CustomFields.c.*%20from%20Incidents \
--header 'authorization: Basic <base64-encoded-username+:+password>' \
--header 'osvc-crest-application-context: <some-comment>'

To get the valid values for a custom field, send a GET request that uses RightNow Object Query (ROQL) like this:

curl --request GET \
--url https://<site.domain>/services/rest/connect/latest/queryResults/?query=select%20CustomFields.c.skillType%20from%20Incidents%20where%20CustomFields.c.skillType%20IS%20NOT%20NULL \
--header 'authorization: Basic <base64-encoded-username+:+password>' \
--header 'osvc-crest-application-context: <some-comment>'

The GenericField definition in the Oracle B2C Service WSDL at http://<sitename.domain>/services/soap/connect/chat_soap?wsdl=server describes the dataType and dataValue structure:

<xs:element name="GenericField" type="GenericField"/>
  <xs:complexType name="GenericField">
    <xs:sequence>
      <xs:element name="DataValue" type="DataValue" minOccurs="1" maxOccurs="1" nillable="true"/>
    </xs:sequence>
  <xs:attribute name="dataType" type="DataTypeEnum" use="optional"/>
  <xs:attribute name="name" type="xs:string" use="required"/>

Like the customerInformation fields, the same casing applies to the customProperties map counterparts (the WSDL’s DataValue is dataValue in the map, for example).

Configure the Fields in the Dialog Flow

These steps describe the dialog flow configuration process for declaring the customProperties object and setting its various values.

Step 1: Declare the Custom Properties Variable

In the context node, define a map variable for the customProperties property in the System.AgentInitiation component. It’s a JSON object that can hold the chat customer information and custom field values. In the following example, this variable is declared as liveChatInfo:

context:
  variables:
    size: "PizzaSize"
    type: "PizzaType"
    crust: "PizzaCrust"
    iResult: "nlpresult"
    interfaceId: "string"
    categoryId: "string"
    skillType: "string"
    liveChatInfo: "map"

Step 2: Set the Values for the customProperties Map Variable

Between the start state and the System.AgentInitation component definition, you need to set the values that you need for the custom property map variable. You can set them through a custom component, or through a series of value-setting components in the dialog flow definition. Here’s an example of the latter approach.

states:
  ...

  setSkillType:
    component: "System.SetVariable"
    properties:
      value: "pizza" 
      variable: "skillType"
    transitions:
      next: "setCategory"
    
  setCategory:
    component: "System.SetVariable"
    properties:
      value: "604"
      variable: "categoryId"
    transitions:
      next: "setLiveChatInfo"

Step 3: Define the Fields for the customProperties Map Variable

Whether you set the map values through a custom component or through the dialog flow, you need to structure the map object. Use the standard object formats unless the agent integration channel was created before version 20.1 or the channel connects to an Oracle B2C Service version that's earlier than 19A. Here's an example of the standard format:


  setLiveChatInfo:
    component: "System.SetVariable"
    properties:
      variable: "liveChatInfo"
      value:
        customerInformation: 
          categoryID:
            id: "${categoryId}"             
        customFields: 
          - name: "c$skilltype"
            type: "STRING"
            value: "${skillType}"
    transitions:
      next: "agentInitiation"

Step 4: Add the customProperties to the System.AgentInitiation Component

Finally, add the customProperties property to the System.AgentInitiation component and define it using an expression that accesses the map variable value.

  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      subject: "A customer needs help regarding ${skillType}."
      agentChannel: "ServiceCloudIntegration"
      waitingMessage: "Let me connect you with someone who can further assist you."
      resumedMessage: "Please wait, someone will be with you shortly."
      rejectedMessage: "Sorry no one is available now."
      errorMessage: "We're sorry! We're having system issues and we can't connect you with an agent."
      customProperties: "${liveChatInfo.value}"
    transitions:
      actions:
        accepted: "agentConversation"
        rejected: "initiationRejected"
        error: "tryAgain"
  initiationRejected:
    component: "System.Output"
    properties:
      text: "Perhaps it's outside their working hours or it's a holiday."
    transitions:
      return: "tryAgain"
  tryAgain:
    component: "System.Output"
    properties:
      text: "Please try again later."
    transitions:
      return: "tryAgain"

Oracle Cloud Infrastructure Documentation

The incidentID Property

The Standard customerInformation Object

The Legacy customerInformation Object

The Standard customFields Object

The Legacy customFields Object

Configure the Fields in the Dialog Flow

Step 1: Declare the Custom Properties Variable

Step 2: Set the Values for the customProperties Map Variable

Step 3: Define the Fields for the customProperties Map Variable

Step 4: Add the customProperties to the System.AgentInitiation Component