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.

1. Click to open the side menu, select Development, and then select Channels.

2. Click Agent Integrations, and then click + Add Agent Integration.

3. Enter a name and an optional description for this channel.

   When you use the System.AgentInitiation and System.AgentConversation components in your dialog flow to enable the transition to, and from, Oracle B2C Service, you must use this name for their agentChannel properties.

4. Choose Service Cloud from the Integration Type menu.

5. Enter the user name and password for an Oracle B2C Service staff member who has the necessary profile permissions.

6. 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.

7. (Optional) Increase or decrease Session Expiration (minutes). This value is used to determine when the System.AgentConversation 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.

8. Click Create.

9. To enable the skill to interact with the agent framework, enable the channel by switching Interaction Enabled to On.

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.

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

   If your instance is provisioned on Oracle Cloud Platform (as all version 19.4.1 instances are), then the switch's name is Skill Conversation.

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:

1. Initiate the live-agent transfer.

   1. Add a state for the System.AgentInitiation component.

   2. 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), the System.AgentInitiation component allows the transition to the next state, which is typically defined for the System.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 a resumedMessage property to the System.AgentInitiation state to prevent such customers from receiving a misleading Resuming chat with agent message.

2. 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, like bye. When the skill detects one of these keywords, the System.AgentConversation component ends the live-chat session and triggers its next 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
   
   The errorMessage property and the error 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).

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}"

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

{
    "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"
                }
            ]
        }
    ],

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 the id sub-property.

• organizationID: Pass a value of type int in the id sub-property.

• productID: Pass a value of type int in the id sub-property.

• categoryID: Pass a value of type int in the id sub-property.

This example sets the contactID.

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

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>'

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.

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).

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>'

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).

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

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

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

• Simple fields:

  • name: The field's column name (lower case) preceded by c$.

  • type: Allowable values are BOOLEAN, DATE, DATETIME, INTEGER, LONG, STRING, and DECIMAL.

  • value: The field's value.

• Menu field:

  • name: The field's column name (lower case) preceded by c$.

  • value: You can set the value to either the field's ID or the menu item's text. Notice that this object doesn't have a type property.

    Tip:

    To find the ID for a menu item, open the custom field's details page from the Oracle B2C Service desktop Service Console. Hover over a menu item and wait for several seconds. The tool tip will appear and show the ID for that item.

Here's an example:

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

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>'

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>'

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}"

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>'

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).

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