Live Agent Transfer
If you have Oracle B2C Service Chat, you can enhance your skills to offer the choice of escalating the conversation to an agent whenever the skill senses that the customer is stuck or frustrated, thus increasing customer satisfaction.
Oracle Digital Assistant lets you integrate your skill with a live agent system in two ways:
- You can integrate with version 18C (and later) of Oracle B2C Service through an Agent Integrations channel as described here.
- You can integrate with a webhook channel as described in the Transfer Digital Assistant Chats to Live Agents solution.
The Live-Agent-Transfer Framework in Action
If a skill determines that the customer wants or needs to speak to a person, the skill connects to Oracle B2C Service and then displays a message that it's waiting for the agent to join the conversation. Oracle B2C Service sends a chat request to one of the live agents who are monitoring an agent chat console. After the agent accepts the request, the framework sends the customer's chat history and, optionally, a list of supported actions that the agent can send back to the bot. After the agent connects with the customer, the skill passes the messages between the customer and the agent until the user or agent terminates the session or the session expires.
How the Live-Agent-Transfer Framework Works
- You configure an Agent Integration channel using the credentials
provided to you by an Oracle B2C
Service administrator, and you reference this channel from the
System.AgentInitiation
andSystem.AgentConversation
components in your skill. - The
System.AgentInitiation
component connects the skill's conversation to Oracle B2C Service. Optionally, the component can provide a list of supported actions that an agent can send to theSystem.AgentConversation
component. - The
System.AgentConversation
component initiates a chat request with Oracle B2C Service, which, in turn, sends the request to an agent's chat console. After the agent accepts the chat request, the component sends subject text, the conversation history, and, if specified in theSystem.AgentInitiation
component, the supported actions. The component then manages the interchange between the skill and the agent. Beginning with Oracle B2C Service version 19A, both the user and the agent can attach images to the conversation. - The session can end in one of the following ways:
- The agent terminates the session.
- The agent sends one of the supported actions, the skill terminates the session, and the skill transitions to the state that corresponds with the action.
- The customer enters one of the specified exit keywords, such as bye or goodbye.
- The session expires after a period of inactivity.
- There is a problem with the connection to Oracle B2C Service.
Integrate a Skill with a Live Agent
Here are the high-level steps for integrating a skill with an existing Oracle B2C Service interface. The next topics describe each step in more detail.
-
Create an Agent Integration channel: The channel allows the skill to communicate with Oracle B2C Service.
-
Enable Insights: In the skill's Settings
page, switch the Enable Insights option to On to enable the framework to pass the conversation history to the live agent.
-
Configure the Agent-Transfer Dialog Flow: Add the
System.AgentInitiation
andSystem.AgentConversation
components to the dialog flow.- The
System.AgentInitiation
component initiates the handoff to Oracle B2C Service. - The
System.AgentConversation
handles the interaction between the skill and the agent.
You can find templates for these components from the Flow
page by clicking + Add Component, and then clicking Transfer from skill to Human Agent.
- The
Create an Agent Integration Channel
You use an Agent Integration channel to configure the connections between skills and the live-agent system.
Before you begin, obtain the credentials of an Oracle B2C Service staff member who's associated with a profile that has the following permissions:
- Access to the desired Oracle B2C Service interface
- Account Authentication and Session Authentication for Public SOAP API
- Account Authentication for Agent Browser User Interface
Contact an Oracle B2C Service administrator if you don't have this information.
You also need to confirm that your Oracle B2C Service Account Manager has enabled the Chat Custom Interface API and the Chat Third-Party Queue Integration API.
-
Click
to open the side menu, select Development, and then select Channels.
- Click Agent Integrations, and then click + Add Agent Integration.
-
Enter a name and an optional description for this channel.
When you use the
System.AgentInitiation
andSystem.AgentConversation
components in your dialog flow to enable the transition to, and from, Oracle B2C Service, you must use this name for theiragentChannel
properties. -
Choose Service Cloud from the Integration Type menu.
-
Enter the user name and password for an Oracle B2C Service staff member who has the necessary profile permissions.
-
Define the domain name and host name prefix.
If you have access to Oracle B2C Service, you can derive these values from the URL that you use to launch the Agent Browser User Interface. For example, if the URL is
sitename.exampledomain.com
, then the host name prefix issitename
and the domain name isexampledomain.com
.If the channel is connecting to Oracle B2C Service version 19A or later, and you have multiple interfaces, then you must include the interface ID in the host (site) name . For example, for the interface that has an ID of 2, you would use something like
sitename-2.exampledomain.com
. -
(Optional) Increase or decrease Session Expiration (minutes). This value is used to determine when the
System.AgentConversation
component should trigger theagentLeft
andexpired
actions.If the Oracle B2C Service
CS_IDLE_TIMEOUT
is equal to or more than the Session Expiration value, thenexpired
is triggered when neither the end-user nor the agent sends a message within the session expiration limit. IfCS_IDLE_TIMEOUT
is less than the Session Expiration value, then Oracle B2C Service terminates the chat and theagentLeft
action is triggered instead.If your instance is provisioned on the Oracle Cloud Platform (as all version 19.4.1 instances are), then the service uses 15 minutes instead of the Session Expiration setting.
By default,
CS_IDLE_TIMEOUT
is 10 minutes. To view or change your Oracle B2C Service instance's settings, open the Oracle B2C Service desktop Service Console, click Navigation, click the first Configuration item in the menu, and click Configuration Settings. Then search the forCS_IDLE_TIMEOUT
, which is in the Chat folder. -
Click Create.
-
To enable the skill to interact with the agent framework, enable the channel by switching Interaction Enabled to On.
Enable Conversation History Transfer
You must turn on logging to enable the live-agent transfer framework to pass the conversation history to a live agent. When you enable this option, the agent's chat console displays the customer's conversation that occurred before the handoff to the agent.
The conversation history is truncated after 4000 characters.
Configure the Agent Transfer Dialog Flow
There are several ways that your dialog flow can direct customers to a live agent. For example:
-
You can provide a specific option for talking with an agent.
-
You can execute a path that gathers necessary customer information before handing someone off to an agent.
-
You can create a handler for unresolved intents that tranfers the customer to an agent.
-
You can create an agent-transfer intent.
In this example, the GetAgent
intent is trained to understand distress calls like help me please!
intent:
component: "System.Intent"
properties:
variable: "iResult"
transitions:
actions:
OrderPizza: "resolvesize"
CancelPizza: "cancelorder"
GetAgent: "agentInitiation"
unresolvedIntent: "agentInitiation"
Here are the basic steps for configuring the dialog flow:
-
Initiate the live-agent transfer.
-
Add a state for the
System.AgentInitiation
component. -
Set the state's
agentChannel
property to the name of the Agent Integration channel that you configured for the live-agent system.
After the Agent Integration channel establishes a connection and Oracle B2C Service sends the chat request to its queue (that is, after it creates a help ticket), theSystem.AgentInitiation
component allows the transition to the next state, which is typically defined for theSystem.AgentConversation
component (agentConversation
in the following example).agentInitiation: component: "System.AgentInitiation" properties: agentChannel: "ServiceCloudIntegration" nlpResultVariable: "iResult" waitingMessage: "Waiting for an agent..." rejectedMessage: "Agents are not available right now." resumedMessage: "We're connecting you to an agent..." errorMessage: "Oops! We're having system issues. We're sorry, but we can't connect you with an agent right now." transitions: actions: accepted: "agentConversation" rejected: "tryAgain" error: "tryAgain" tryAgain: component: "System.Output" properties: text: "Please try again later." transitions: return: "tryAgain"
Tip:
Customers may repeatedly request a live chat even though their requests have already been queued in the agent's chat console. Add aresumedMessage
property to theSystem.AgentInitiation
state to prevent such customers from receiving a misleading Resuming chat with agent message. -
-
Add and configure the
System.AgentConversation
component. While the dialog engine is in the state defined for this component, the skill passes messages back and forth between the customer and the agent. The skill listens for exit keywords in the customer input, likebye
. When the skill detects one of these keywords, theSystem.AgentConversation
component ends the live-chat session and triggers itsnext
transition.Here's an example:
agentConversation: component: "System.AgentConversation" properties: agentChannel: "ServiceCloudIntegration" nlpResultVariable: "iResult" errorMessage: "Oops, we lost connection with the agent. If you need further help, please call customer support." exitKeywords: "bye, exit, take care, goodbye, quit" expiryMessage: "Your chat with the agent timed out." conclusionMessage: "Your chat with the agent has ended." waitMessage: "You are number ${system.message.messagePayload.position} in the queue. Your waiting time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}." transitions: next: "endPrompt" actions: agentLeft: "endPrompt" expired: "endPrompt" error: "endPrompt" endPrompt: component: "System.Output" properties: text: "Returning you to your bot." transitions: return: "endPrompt"
Note
TheerrorMessage
property and theerror
action only work with instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure).
Enable Agents to Specify the Transition Action
If you want to enable the agent to specify which state to transition to after the live-chat session ends, use the agentActions
property in the System.AgentInitiation
component to list the supported actions that the agent can send, and then use the System.AgentConversation
component to map the actions to states.
When the agent accepts the chat request, the chat console displays the supported actions, each of which is preceded by a slash (these are referred to as slash actions).

If the agent sends any of the slash actions, the action is sent to the live-agent transfer framework, and the skill terminates the live chat. If the System.AgentConversation
has a transition for that action, the flow transitions to the named state. Note that the conclusionMessage
isn't output if the agent sends a slash action.

Override Queue Position and Wait Time Message
By default, when a chat request is submitted, the service returns a message about the queue position and wait time, which the skill outputs. For example, the message might be:
You are in position {0} in our queue. Expected wait time is {1} minute(s) {2} second(s)
System.AgentConversation
component's waitMessage
property to define your own custom message. As illustrated by the following snippet, you can create a message that returns the queue and wait time status using the system.message.messagePayload.position
and system.messagePayload.waitTime
properties, respectively:"You are at number ${system.message.messagePayload.position} in the queue. Your wait time is ${system.message.messagePayload.waitTime}."
You can tailor the message content by combining these properties with built-in Apache FreeMarker operations, such as the then
operation in the following snippet. Here, it allows the skill to output content that's specific to either minutes or seconds. For wait times of 60 seconds or longer (waitTime>60
), the skill outputs You are at number 9 in the queue. Your wait time is 1 mins. Otherwise, it outputs You are at number 9 in the queue. Your wait time is 55 seconds. waitMessage: "You are at number ${system.message.messagePayload.position} in the queue. Your wait time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}"
Handle Agent Initiation Rejection and System Errors
Your dialog flow needs to handle errors that might occur during agent initiation. When the System.AgentInitiation
component tries to initiate a connection with the live-agent system, it might return an error
or rejected
action. Also, it might invoke a system error if there is a developer-caused issue.
-
rejected
action: This action is triggered when Oracle B2C Service rejects the connection request. Some of the reasons for rejecting a connection request are:- No agents are available (requires
allowTransferIf
andqueueId
properties) - It's outside of the configured operating hours
- It's a holiday
- There's a problem with the chat server
Note that if you don't set
allowTransferIf
andqueueId
, the rejected action will not occur when no agents are available, instead, the transfer will remain in a wait condition.When Oracle B2C Service rejects a connection request, the skill displays a rejected message, which is Agent rejected by default. Then it transitions to the state that's mapped to the
rejected
action. You can use therejectedMessage
property in theSystem.AgentInitiation
component to provide a custom message.Tip:
If you have admin access to the Oracle B2C Service desktop Service Console, you can view the operating hours and holidays. From the navigation pane, click Configuration, click Site Configuration, double-click Interfaces, and then click Chat Hours. - No agents are available (requires
-
error
action: This action is triggered when there's a problem establishing a connection with Oracle B2C Service. For example, the password in the Agent Integration channel is no longer valid, or there's a problem with the Oracle B2C Service server.When this type of error occurs, the skill displays the following message by default, and then transitions to the state that's mapped to the
error
action.Error transferring to agent, the reason is: <reason>, Please contact your system administrator to resolve this error.
You can use the
errorMessage
property in theSystem.AgentInitiation
component to override the default message. -
System errors: When the agent integration channel doesn't exist or is disabled, the skill invokes a system error. By default, the skill displays the message "Oops I'm encountering a spot of trouble. Please try again later..." Unfortunately, until a developer fixes the problem, it won't help the bot user to try again. Therefore, you might want your dialog flow to better handle these errors by adding an
error
transition, which goes to a state that outputs a more helpful customer-facing message. (This is different from theerror action
). Alternatively, you can modify the default message by going to Settings > Configuration and editing Unexpected Error Prompt. However, this change affects the skill globally.Note that when you validate a dialog flow, the validator will let you know if the agent integration channel is missing or disabled, so remember to do that before you test your skill or release it to the public.
Here are some ways to diagnose a system error:
-
Click Validate in the skill to validate the dialog flow.
-
Run the skill in the Preview. When the error occurs, the error state and message (reason) are displayed in the Conversation tab.
-
In the state to which the
error
transition routes the flow, output a string that includes the Freemarker template${system.errorAction}
, which prints the error message (reason).
-
Here's an example of handling system errors and the error
and rejected
actions.
agentInitiation:
component: "System.AgentInitiation"
properties:
agentChannel: "B2CServiceIntegration"
nlpResultVariable: "iResult"
waitingMessage: "Let me connect you with someone who can further assist you."
resumedMessage: "Someone will be with you shortly."
errorMessage: "Oops! We're having system issues and we can't connect you with an agent right now."
rejectedMessage: "Unfortunately, no one's available right now."
transitions:
actions:
accepted: "agentConversation"
rejected: "initiationRejected"
error: "tryAgain"
error: "agentInitiationSystemError"
initiationRejected:
component: "System.Output"
properties:
text: "Perhaps it's outside their working hours or it's a holiday."
transitions:
return: "initiationRejected"
tryAgain:
component: "System.Output"
properties:
text: "Please try again later."
transitions:
return: "tryAgain"
agentInitiationSystemError:
component: "System.Output"
properties:
text: "I seem to be having a connection problem. Can you please email email@example.com to let them know?"
transitions:
return: "done"
Configure When to Attempt Agent Transfer
By default, the System.AgentConversation
component
transfers the conversation to Oracle B2C
Service regardless of whether there are any available agents. However, you have options for when
to transfer the chat to a human agent.
This feature works only with instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure).
If you would like to change the rules about when to transfer to an agent, you can use the System.AgentInitiation
component's allowTransferIf
and queueId
properties to configure when the component should attempt to transfer the conversation to a live agent. Your choices are:
agentsAreRequestingNewEngagements
: Transfer only if at least one agent who is assigned to the specified queue has requested a new engagement (pulled a chat) or, if chats are automatically routed to available agents, there is at least one agent assigned to the queue who hasn't reached their maximum number of chats. With this option, the user doesn't have to wait for an agent.agentSessionsAreAvailable
: Transfer if any agents who are assigned to the queue haven't reached their maximum number of chats regardless of whether they've requested a new engagement (pulled a chat) or, if chats are automatically routed to available agents, there is at least one agent assigned to the queue who hasn't reached their maximum number of chats. The user may have to wait if all the agents are involved in long-running conversations or are doing some post-chat follow-up.agentsAreAvailable
: In the case where agents must request new engagements (pull chats), transfer even if none of the queue's agents have requested a new engagement or all the queue's agents have reached their maximum number of chats. In the case where chats are automatically routed to available agents, transfer even if they all the queue's agents have reached their maximum number of chats. The user may have a long wait.
You should insure that the queue that's identified by the queueId
property is the actual queue that the Oracle Digital Assistant chat rules will route the conversation to.
Tip:
To get the queue ID, ask someone who has configuration permissions to open the Service Console and get the ID from Chat Queues in the System Menus page. When you hover the mouse over the queue name, it displays the ID. Sometimes it takes a few seconds for the ID tooltip to appear.Enable Agents to Specify the Transition Action
If you want to enable the agent to specify which state to transition to after the live-chat session ends, use the agentActions
property in the System.AgentInitiation
component to list the supported actions that the agent can send, and then use the System.AgentConversation
component to map the actions to states.
When the agent accepts the chat request, the chat console displays the supported actions, each of which is preceded by a slash (these are referred to as slash actions).

If the agent sends any of the slash actions, the action is sent to the live-agent transfer framework, and the skill terminates the live chat. If the System.AgentConversation
has a transition for that action, the flow transitions to the named state. Note that the conclusionMessage
isn't output if the agent sends a slash action.

Tutorial: Live Agent Transfer
You can get a hands-on look at transferring to a live agent by walking through this tutorial: Integrate a Skill with Oracle Service Cloud Live Chat.
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 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 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 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 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 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 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.
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 thatinterfaceID
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 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 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:
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
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 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
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
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
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
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"
Tutorial: Pass Customer Information to a Live Chat
You can get a hands-on look at passing information to a live chat by walking through this tutorial, which is part 2 of a series: Pass Customer Information to a Live Chat.
Enable Attachments
Agent-integration channels that connect to Oracle B2C Service version 19A and later support attachment of images, audio, video, and files to the conversation.
If the following conditions are met, then both users and agents can click an attachments button to attach the object to the conversation.
-
For user-initiated attachments, the messaging platform must support attachments.
-
The skill's agent-integration channel must have been created using Oracle Digital Assistant 20.1 or later. If the channel existed prior to version 20.1, then you must delete the channel and re-create it.
-
The channel must connect to Oracle B2C Service version 19A or later.
Note that when the above conditions are true, you must use the standard format to pass custom field values as described in The Standard customFields Object.
Create an Incident Report
You can create an incident report (or service request) for Oracle B2C Service or Oracle Fusion Service from any skill.
To create an incident report from your skill:
-
Go to Settings > Additional Services > Customer Service Integration and create an integration with the needed service.
You only need to do this once per instance.
-
Add the incident creation component to your flow. For the Visual Flow Designer, see Incident Creation. For YAML, see System.IncidentCreation.
If you have created a Oracle Fusion Service integration and have selected Allow only signed-in users to create service request as the authentication type, you also need to do the following:
- Set the Incident Creation component's Requires
Authentication setting to
True
. - Add an OAuth Account Link component to the dialog flow to handle user authentication. For the Visual Flow Designer, see OAuth Account Link. For YAML, see System.OAuthAccountLink.
- Set the Incident Creation component's Requires
Authentication setting to
Tip:
After creating and configuring the Incident Creation component, click Validate in the page's banner to validate the skill. Among other things, this validation will ensure that you have entered a service name in the Incident Creation component that matches the name you have given to the customer service integration that you created.Get Survey Information
If you want to ask the customer to fill out a survey about the conversation with the agent, you can get the conversation's session ID and engagement ID when the chat session is established, and then pass those values to a survey service when the conversation ends.
Let's say, for example, that you used a survey service such as Oracle Feedback Cloud Service to develop a survey which takes session and engagement parameters. When the agent conversation ends, you can display a link to the survey form, such as https://example.com?session=12345&surveyid=12345
. Here's how to use the System.AgentInitiation
component's chatResponseVariable
property to get the IDs that you need, and then use the System.AgentConversation.conclusionMessage
property to pass them in a link to a survey service.
When the chat session is established with the live agent, Oracle B2C Service sends the following payload for channels that are created in version 20.1 and later and connect to Oracle B2C Service 19A and later. This is referred to as the standard format.
{
"sessionId": "string", // agent session id
"completedSurveyId": int,
"engagementId": int, // survey id
"cancelledSurveyId": int
}
For channels were created prior to 20.1, and for channels that connect to a Oracle B2C Service instance that's earlier than 19A, it sends this payload. This is referred to as the legacy format.
{
"sessionId": "string", // agent session id
"completedSurveyId": {
"id": int
},
"engagementId": { // survey id
"id": int
},
"cancelledSurveyId": {
"id": int
}
}
The dialog engine stores this payload in the map variable that's referenced by the System.AgentInitiation.chatResponseVariable
property. (If System.AgentInitiation.chatResponseVariable
isn't defined, then the payload is discarded.)
In the following example that uses the standard format, the System.AgentConversation
component outputs a survey link after the agent conversation ends. The link includes the session and engagement ID from the map that was named by the chatResponseVariable
property.
context:
variables:
agentSystemResponse: "map" # chat request response is stored in this variable.
...
states:
...
agentInitiation:
component: "System.AgentInitiation"
properties:
agentChannel: "B2CServiceIntegration"
nlpResultVariable: "iResult"
chatResponseVariable: "agentSystemResponse"
transitions:
actions:
accepted: "agentConversation"
rejected: "tryAgain"
error: "tryAgain"
agentConversation:
component: "System.AgentConversation"
properties:
agentChannel: "B2CServiceIntegration"
nlpResultVariable: "iResult"
exitKeywords: "bye, exit, take care, goodbye, quit"
expiryMessage: "Your chat with the agent timed out."
conclusionMessage: "Can you please fill out this survey: <PUT SURVEY URL HERE>?session=${agentSystemResponse.value.sessionId}&surveyid=${agentSystemResponse.value.engagementId}"
transitions:
next: "endPrompt"
actions:
agentLeft: "endPrompt"
expired: "sessionExpired"
error: "agentConversationError"
Tip:
You can configure the survey to take other parameters, such as the user's name and email address.Transfer the Chat to a Specific Oracle B2C Service Queue
Oracle B2C
Service uses chat rules and queues to sort incoming chat requests based on Chat Customer Information
and Incident custom field values. By default, the skill routes all agent chats to the default
queue. However, you can take advantage of the System.AgentInitiation
component's customProperties
property to pass in the values for a specific rule
that will filter the chat request to the desired queue.
An administrator can set up a Oracle B2C
Service queue, profile, and chat rules to route a skill's chat request to the appropriate agents. For example, the Oracle B2C
Service interface might have a chat rule that if the fromBot
custom field is set to Yes
, then add the chat request to the Bot
queue. When its rule base doesn't have a rule for an incoming chat, then it sends the chat request to a default queue. (You can learn more about rules at Business Rules in Using Oracle B2C
Service.)
Before you begin, you'll need the names and valid values of the custom fields or customer information (or both) that have been defined for the queue's chat rule. If you have admin access to the Oracle B2C Service desktop Service Console, then you can see the chat rules from the Configuration > Site Configuration > Rules > Chat page. Otherwise, ask your Oracle B2C Service administrator to provide this information.
You'll also need to understand how to structure the map object that you use with the customProperties
property. See Pass Customer Information to a Live Chat.
-
If you haven't already, in the context node, define a map variable to use with the
System.AgentInitiation
component'scustomProperties
property. For example:context: variables: greeting: "string" name: "string" liveChatInfo: "map"
-
Define the fields for the map variable.
Here's an example of the standard format for agent-integration channels that were created in version 20.01 or later and that connect to Oracle B2C Service version 19A or later.
setLiveChatInfo: component: "System.SetVariable" properties: variable: "liveChatInfo" value: customFields: - name: "c$frombot" type: "BOOLEAN" value: 1 transitions: next: "agentInitiation"
Here's an example of the legacy format for agent-integration channels that were created prior to version 20.01 or that connect to a version that is earlier than Oracle B2C Service version 19A.
setLiveChatInfo: component: "System.SetVariable" properties: variable: "liveChatInfo" value: customFields: - name: "c$frombot" dataType: "BOOLEAN" dataValue: booleanValue: true transitions: next: "agentInitiation"
-
Add the
customProperties
property to theSystem.AgentInitiation
component, and set it to the value of your map variable. For example:agentInitiation: component: "System.AgentInitiation" properties: agentChannel: "B2CServiceIntegration" nlpResultVariable: "iResult" customProperties: "${liveChatInfo.value}" waitingMessage: "Waiting for an agent..." rejectedMessage: "Agents are not available right now." resumedMessage: "We're connecting you to an agent..." errorMessage: "Oops! We're having system issues. We're sorry, but we can't connect you with an agent right now." transitions: actions: accepted: "agentConversation" rejected: "tryAgain" error: "tryAgain" tryAgain: component: "System.Output" properties: text: "Please try again later." transitions: return: "tryAgain"
Tutorial: Transfer to a Live Chat Queue
You can get a hands-on look at transferring to a live chat queue by walking through this tutorial, which is part 3 of a series: Transfer a Chat Session to a Live Chat Queue.