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.
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
${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 theincidentId
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 theid
sub-property. -
organizationID: Pass a value of type
int
in theid
sub-property. -
productID: Pass a value of type
int
in theid
sub-property. -
categoryID: Pass a value of type
int
in theid
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 byc$
. -
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 byc$
. -
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 atype
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.
- 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 itcustomerTicketId
. - If you want to include any
customerInformation
properties in the custom properties, define a variable of typeList
to hold these properties. In this example we'll call itcustInfo
. - If you want to include any of the
customFields
properties in the custom properties, define a variable of typeMap
to hold these properties. In this example we'll call itcustFields
.
You declare flow variables by selecting the given flow on the Flow Designer page, clicking the Configuration tab, and clicking Add Variable.
- If you want to include the incident ID in the custom properties, define a
variable of type
- 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" } ]
- For
- 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}" }
- 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}
.