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 Agent Initiation and Agent Conversation components to the dialog flow. (In the Visual Flow Designer, these components are available through the Agent Communication template.)
- The Agent Initiation component initiates the handoff to Oracle B2C Service.
- The Agent Conversation component handles the interaction between the skill and the agent.

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 Agent Initiation and Agent Conversation components in your dialog flow to enable the transition to, and from, Oracle B2C Service, you must use this name for their agentChannel 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 is sitename and the domain name is exampledomain.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 Agent Conversation dialog flow component should trigger the agentLeft and expired actions.

If the Oracle B2C Service CS_IDLE_TIMEOUT is equal to or more than the Session Expiration value, then expired is triggered when neither the end-user nor the agent sends a message within the session expiration limit. If CS_IDLE_TIMEOUT is less than the Session Expiration value, then Oracle B2C Service terminates the chat and the agentLeft 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 for CS_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.

In the skill's left navbar, click Settings .
In the General tab, set the Enable Insights switch to On.

Note

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.

Here are the basic steps for configuring the dialog flow:

Add Agent Initiation and Agent Conversation components to the flow. If your skill is in Visual dialog mode (the default), use the Agent Communication template, which contains both of these components.
Initiate the live-agent transfer by setting the Agent Initiation state's Agent Integration Channel 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), the Agent Integration component allows the transition to the next state, which is typically defined for the Agent Conversation component.
Fine tune the messages that the component uses (such as the waiting and resumed messages) in the resource bundle entries for the component. To access these entries, open the skill's Resources Bundle page by clicking, select the Configuration tab, and type agenti in the filter field.

Tip:
Customers may repeatedly request a live chat even though their requests have already been queued in the agent's chat console. If this is the case, you might want to change the value of the systemComponent_AgentInitiation_resumedMessage resource bundle entry from the potentially misleading Resuming chat with agent message to something else more suitable.
Configure the Agent Conversation 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, like bye. When the skill detects one of these keywords, the component ends the live-chat session and triggers its next transition.

You can edit the exit keywords as well as the standard messages that the component uses (such as the expiry and error messages) in the resource bundle entries for the component. To access these entries, open the skill's Resources Bundle page by clicking, select the Configuration tab, and type agentc in the filter field.

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 Agent Actions property in the Agent Initiation component to list the supported actions that the agent can send, and then use the Agent Conversation 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).

Agent console displaying list of supported 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 Agent Conversation component has a transition for that action, the flow transitions to the named state. Note that the conclusion message (stored in the systemComponent_AgentConversation_conclusionMessage resource bundle entry) isn't output if the agent sends a slash action.

Chat console showing that the agent has sent /Order and the chat has terminated.

In the Agent Initiation state, use the Agent Actions property to list the supported actions.
Add a state for the next transition, which is reached when the user terminates the conversation by using an exit keyword, and then add these transition actions:
- Each action that's listed in the Agent Actions property in the Agent Conversation component.
- An agentLeft action for when the agent terminates the live chat without using a slash action or the session times out. See Transition Actions for Agent Conversation.
- An expired action for when a session expires. See Transition Actions for Agent Conversation.
- An error action for when the channel connection fails. See Transition Actions for Agent Conversation.

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)

You can use the Agent Conversation component's B2C Wait Message Override 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.

Handle Agent Initiation Rejection and System Errors

Your dialog flow needs to handle errors that might occur during agent initiation. When the Agent Initiation 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:
- It's outside of the configured operating hours
- It's a holiday
- There's a problem with the chat server
- No agents are available (requires the Allow Transfer If and Queue ID properties)
  Note
  
  The Allow Transfer If and Queue ID properties must be set for a connection to be rejected when no agents are available. Otherwise, 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 the systemComponent_AgentInitiation_rejectedMessage resource bundle entry to provide a custom message. To access this entry, open the skill's Resources Bundle page by clicking , select the Configuration tab, enter agenti in the filter field, and select the systemComponent_AgentInitiation_rejectedMessage key.

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.
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>
```
You can change the message by editing the systemComponent_AgentInitiation_errorMessage resource bundle entry.
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 the error 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).