Integrating Oracle Digital Assistant (ODA) with an Agent System

This project allows ODA (19.1.3 and above) to handover a user chat to a third party Agent Handover system other than Oracle Service Cloud. Project is shipped with mock agent server 'with no UI' that prints out user messages to console. Also a sample implementation to hand over chat to "Oracle Engagement Cloud (19A or above)".

Features

This project extends ODA out of the box features integrating with Oracle Service Cloud to different agent systems, so you will still use the out of the box System.AgentInitiation and System.AgentConversation components; hence your skill is totally abstracted from back-end agent system details. By using ODA built-in system components, the following features are supported:

Passing user conversation history to agent upon initiating a chat request.
Bot user can terminate chat conversation at anytime using the exit keywords specified in System.AgentConversation component.
Upon terminating a chat conversation, Agent can redirect the bot to a specific state as specified in the actions property in System.AgentInitiation component.
Upon terminating a chat conversation, Agent can decide to automatically add a new utterance to an intent.

High level architecture

As described in the below screenshot, this integration uses ODA webhook channel to pass user messages to webhook implementation, webhook implementation calls out your custom agent implementation file that is basically responsible for message transformations between ODA and agent system, and then message sent to agent or ODA depending from where the message originated.

Install

Clone project repository git clone git@github.com:oracle/cloud-asset-oda-agent-handover.git
Navigate to project directory cd cloud-asset-oda-agent-handover and install required libraries npm install
Edit cloud-asset-oda-agent-handover/config/config.js and update ODA webhook details as specified in section Configure ODA Skill. Also you need to update AGENT_IMPL_FILE, For more details check Integrate with a third party agent system

// Digital Assistance Webhook channel details
module.exports.DA_WEBHOOK_URL = "ODA_WEBHOOK_URL";
module.exports.DA_WEBHOOK_SECRET = "ODA_WEBHOOK_SECRET";

// Webhook Implementation
module.exports.PORT = process.env.PORT || 4444;

/**
 * Name of the agent implementation file without the extension.
 * This file exists under oda_agent_handover/src/agentImpl folder
 */
module.exports.AGENT_IMPL_FILE = "mockAgent";

Run webhook using npm start or npm run start:dev the later will start server in development mode with code live reload enabled using nodemon and inspect mode on port 9229 for debugging.
If you make code changes, you can run npm run lint:fix to lint your code using eslint.
If you are running locally on your laptop, you need to expose your webhook to the internet through an SSL connection. For development purposes, you can using ngrok ngrok http 4444

Configure ODA Skill

Create a new Skill for example AgentFramework and replace the generated BOTML with the following sample:

metadata:
  platformVersion: "1.1"
main: true
name: AgentFramework
context:
  variables:
    question: "string"
    myCustomProps: "string"

states:
  setUserEmail:
    component: "System.SetVariable"
    properties:
      value: "CHANGE_TO_YOUR_EMAIL"
      variable: "profile.email"
    transitions: {}
    
  setUserFirstName:
    component: "System.SetVariable"
    properties:
      value: "CHANGE_TO_YOUR_FIRST_NAME"
      variable: "profile.firstName"
    transitions: {}
    
  setUserLastName:
    component: "System.SetVariable"
    properties:
      value: "CHANGE_TO_YOUR_LAST_NAME"
      variable: "profile.lastName"
    transitions: {}
    
  setCustomProperties:
    component: "System.SetVariable"
    properties:
      variable: "myCustomProps"
      value:
        Product: 
          - Name: "Product X"
            Serial: "CUSTOM_PRODUCT_SERIAL_NUMBER"
        Country: 
          - City: "MY_CITY"
            Code: "MY_COUNTRY"
        Profile: 
          - mobileNumber: "CHANGE_TO_YOUR_MOBILE_NUMBER"
            userName: "CHANGE_TO_ANY_USER_NAME"

  start:
    component: "System.Text"
    properties:     
      prompt: "How can I help you?"
      variable: "question"
    
  startContactAgent:
    component: "System.AgentInitiation"
    properties:
      subject: "${question}"
      agentChannel: "AgentFrameworkChannel"
      agentActions: "MyAction,Payments"
      waitingMessage: "Chat accepted, waiting for agent to join"
      rejectedMessage: "Apologies no agent is available at the moment"
      customProperties: "${myCustomProps.value}"
    transitions:
      actions:
        accepted: "agentConversation"
        rejected: "rejected"
        
  agentConversation:
    component: "System.AgentConversation"
    properties:
      agentChannel: "AgentFrameworkChannel"
      exitKeywords: "bye,thanks,thank you"
      conclusionMessage: "Agent left the conversation, we will redirect you back again to our automated bot."
    transitions:
      actions:
        MyAction: "agentRedirection"
        Payments: "agentRedirection"
      next: "exit"
      
  agentRedirection:
    component: "System.Output"
    properties:
      text: "Agent left conversation and redirected you to this state."
      keepTurn: false
    transitions:
      next: "exit"
      
  rejected:
    component: "System.Output"
    properties:
      text: "Agent Rejected chat request."
      keepTurn: true
      
  exit:
    component: "System.Output"
    properties:
      text: "End of Agent Handover demo."
    transitions:
      return: "start"

Create a new channel and point it to your webhook implementation URL https://ADDRESS:PORT/bot/message If you are using ngrok to expose your webhook implementation, then the that URL would be https://NGROK_URL/bot/message
As mentioned in step (3) in the installation section, update the ODA_WEBHOOK_URL and ODA_WEBHOOK_SECRET to map to the details of the newly created channel.
Route new channel to your skill.
Note down the channel name, and then back to your skill BOTML, update the System.AgentInitiation component in state startContactAgent and make sure that agentChannel property is set to the name of your channel you created. Apply the same for the System.AgentConversation component in state agentConversation

  startContactAgent:
    component: "System.AgentInitiation"
    properties:
      subject: "${question}"
      agentChannel: "AgentFrameworkChannel"
      agentActions: "MyAction,Payments"
      waitingMessage: "Chat accepted, waiting for agent to join"
      rejectedMessage: "Apologies no agent is available at the moment"
      customProperties: "${myCustomProps.value}"
    transitions:
      actions:
        accepted: "agentConversation"
        rejected: "rejected"

  agentConversation:
    component: "System.AgentConversation"
    properties:
      agentChannel: "AgentFrameworkChannel"
      exitKeywords: "bye,thanks,thank you"
      conclusionMessage: "Agent left the conversation, we will redirect you back again to our automated bot."
    transitions:
      actions:
        MyAction: "agentRedirection"
        Payments: "agentRedirection"
      next: "exit"

To ensure conversation history is passed along, make sure to enable conversation logging.

Payloads

Below are the details of the message formats exchanged between the webhook implementation and agent server.

From Webhook to Agent

All messages sent from Webhook to agent system will pass a botUser object. This identifies the user conversation session in ODA. Agent system should store this object and send it back along will all messages to webhook. ODA will use this value to properly route messages to the correct user conversation session.

Request chat: sent when a user request chat with an agent.

{
  "botUser": {
      "userId": "3281467"
  },
  "conversationHistory": [
    {
      "payload": "start",
      "id": "5d59878d-b451-4dca-b348-bab296a8d896",
      "source": "USER",
      "createdOn": 1552039641121
    },
    {
      "payload": "How can I help you?",
      "id": "ba910a5a-74f9-41bb-8b31-222c3384de5d",
      "source": "BOT",
      "createdOn": 1552039641205
    },
    {
      "payload": "I want to speak with an agent",
      "id": "407aa4b5-7c40-4ff0-a1b4-3ec5d24e7cd6",
      "source": "USER",
      "createdOn": 1552039647643
    }
  ],
  "actions": [
    {
      "action": "MyAction",
      "description": "MyAction",
      "label": "MyAction"
    },
    {
      "action": "Payments",
      "description": "Payments",
      "label": "Payments"
    }
  ],
  "firstName": "CHANGE_TO_YOUR_FIRST_NAME",
  "lastName": "CHANGE_TO_YOUR_LAST_NAME",
  "email": "CHANGE_TO_YOUR_EMAIL",
  "message": "I want to speak with an agent",
  "metadata": {
    "Country": [
      {
        "City": "MyCity",
        "Code": "MyCountry"
      }
    ],
    "MyProduct": [
      {
        "Serial": "CUSTOM_PRODUCT_SERIAL_NUMBER",
        "Name": "Product X"
      }
    ],
    "Profile": [
      {
        "mobileNumber": "CHANGE_TO_YOUR_MOBILE_NUMBER",
        "userName": "CHANGE_TO_ANY_USER_NAME"
      }
    ]
  }  
}

conversationHistory: an array containing the full conversation history between user and bot. It is the agent system responsibility to parse it and outputs a proper interface in agent system.

actions: an array of action objects passed to agent. An agent can use the the value of action.action property to terminate chat with user and redirect bot to a specific state in BOTML. For more details, check section Agent Action Transition.

metadata: a JSON object holding custom properties, this maps to the customProperties property in System.AgentInitiation state. Basically this is any custom metadata that can be passed along chatRequest.

Send Chat Message: user sends a chat message to agent during an ongoing conversation.
```
{
  "botUser": {
    "userId": "3246969"
  },
  "message": "This is a message from bot to agent",
  "sessionId": "123456"
}
```
sessionId: a unique value that identifies user chat session in agent system. This is a value passed from agent system upon accepting a chat request. For more details, check section Chat Accepted.
Terminate Chat: user terminates chat conversation with an agent by sending any of the exit key words defined in System.AgentConversation component in stat agentConversation
```
{
  "botUser": {
    "userId": "3246969"
  },
  "message": "terminate chat from bot",
  "sessionId": "123456"
}
```
sessionId: a unique value that identifies user chat session in agent system. This is a value passed from agent system upon accepting a chat request. For more details, check section Chat Accepted.

From Agent to Webhook

Agent back-end system, must POST responses to webhook implementation on https://WEBHOOK_ADDRESS:PORT/agent/message

All messages sent from Agent system to webhook will pass a sessionId property. This identifies the user conversation session in agent system. Webhook implementation will store this property and send it back along will all messages to agent system. Agent system will use this property to properly route messages to the correct user conversation session.

Request chat Accepted: sent when agent accepts a user chat request.

{
  "type": "accepted",
  "payload": {
    "message": "Hello my name is Agent, how can I help you?",
    "sessionId": "123456",
    "botUser": {
      "userId": "3246969"
    }
  }
}