Oracle Cloud Infrastructure Documentation

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 Agent Integration component's Custom Properties property. Here's the top-level structure of the map: 

incidentID: # type int
customerInformation: # chat customer information object
customFields: # incident custom fields object
To reference the map, use an expression something like:
${mapVariableName.value}

See Assemble the Custom Properties Object for an example of assembling the customer information to the send the live agent.

The incidentID Property

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

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 Custom Properties 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.

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 Custom Properties 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.

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 Custom Properties 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 customFields 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 Custom Properties 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 value for the object:

[		
  {
    "name" : "c$text_field",        
    "type" : "STRING",
    "value" : "SILVER"
  },
  {
    "name" : "c$text_area",
    "type" : "STRING",
    "value" : "My package arrived but there were no contents in the box. Just bubble wrap."
  },
  {
    "name" : "c$integer",          
    "type" : "INTEGER",
    "value" : 21
  },
  {
    "name" : "c$yes_no", 
    "type" : "BOOLEAN",
    "value": 1
  },
  {
    "name" : "c$date_field",   
    "type" : "DATE",
    "value" : "2020-02-04T00:00:00+00:00" 
  },
  {
    "name" : "c$date_time",        
    "type" : "DATETIME",
    "value" : "2020-02-04T21:24:18+00:00" 
  },
  {
    "name" : "c$menu",            
    "value" : "12"
  }
]

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

This section discusses the customFields 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 customFields object in the Custom Properties 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. The name property's value is the field's lower-case column name preceded by c$.

Here's an example value for the object:

[		
  {
    "name" : "c$da_text_field",        
    "dataType" : "STRING",
    "dataValue" : {
      "stringValue": "SILVER"
    }
  },
  {
    "name" : "c$da_text_area",
    "dataType" : "STRING",
    "dataValue" : {
      "stringValue": "This is a very long string that is more than 32 characters."
    }
  },
  {
    "name" : "c$da_integer",          
    "dataType" : "INTEGER",
    "dataValue" : {
      "integerValue" :21
    }
  },
  {
    "name" : "c$da_menu", 
    "dataType" : "NAMED_ID",
    "dataValue" : {
      "namedIDValue": {
        "name" : "Item 1"
      }
    }
  },
  {
    "name" : "c$da_is_from_skill",          
    "dataType" : "BOOLEAN",
    "dataValue" : {
      "booleanValue" : true
    }
  },
  {
    "name" : "c$da_date",   
    "dataType" : "DATE",
    "dataValue" : {
      "dateValue" : "2019-10-26"
    }
  },
  {
    "name" : "c$da_datetime",        
    "dataType" : "DATETIME",
    "dataValue" : {
      "dateTimeValue" : "2019-10-26T21:32:52"  
    }
  }
]

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 Custom Properties map counterparts (the WSDL’s DataValue is dataValue in the map, for example).

Assemble the Custom Properties Object

There are many approaches you can use to create the Custom Properties object. The following steps show how to do so by creating a separate variable for each group of properties and then consolidating them in a map.

  1. Declare variables for the parts that you want to include in the Custom Properties object:
    • If you want to include the incident ID in the custom properties, define a variable of type Integer for the incident ID. In this example we'll call it customerTicketId.
    • If you want to include any customerInformation properties in the custom properties, define a variable of type List to hold these properties. In this example we'll call it custInfo.
    • If you want to include any of the customFields properties in the custom properties, define a variable of type Map to hold these properties. In this example we'll call it custFields.

    You declare flow variables by selecting the given flow on the Flow Designer page, clicking the Configuration tab, and clicking Add Variable.

  2. In Set Variable components, assign values to the variables you have created.
    • For customerTicketId, use a value or expression that resolves to an integer.
    • For custInfo, provide the value as JSON map that looks something like this:
      {
  "contactID" : {
    "id" : "${contactId}"
	},  
  "organizationID" : {
    "id" : "${organizationId}"
	},
  "productID" : {
    "id" : "${productId}"
	},
  "categoryID" : {
    "id" : "${categoryId}"
	}
}
    • For custFields, provide the value as a JSON array of objects that looks something like this:
      [		
  {
    "name" : "c$text_field",        
    "type" : "STRING",
    "value" : "SILVER"
  },
  {
    "name" : "c$text_area",
    "type" : "STRING",
    "value" : "My package arrived but there were no contents in the box. Just bubble wrap."
  },
  {
    "name" : "c$integer",          
    "type" : "INTEGER",
    "value" : 21
  },
  {
    "name" : "c$yes_no", 
    "type" : "BOOLEAN",
    "value": 1
  },
  {
    "name" : "c$date_field",   
    "type" : "DATE",
    "value" : "2020-02-04T00:00:00+00:00" 
  },
  {
    "name" : "c$date_time",        
    "type" : "DATETIME",
    "value" : "2020-02-04T21:24:18+00:00" 
  },
  {
    "name" : "c$date_time", 
    "type" : "DATETIME",	  
    "value" : "2020-02-04T21:24:18+00:00" 
  },
  {
    "name" : "c$menu",            
    "value" : "12"
  }
]
  3. Use a Set Variable component to consolidate the variables from the previous step into one map variable.

    For example, you could name the variable liveChatInfo and give it the following value: 

    {
  "incidentId" : "${customerTicketId}",
  "customerInformation" : "${custInfo.value}",
  "customFields" : "${custFields.value}"
}
  4. In the flow's Agent Initiation component, set the value of the Custom Properties property to the value of the consolidated map variable, e.g.: ${liveChatInfo.value}.