Agent Desk Developer Guide

Purpose

The purpose of this document is to describe how to build custom Agent Desk using Agent Manager integration interfaces. Agent Manager is used to manage customer-support conversations with the customers.

Audience

The document is intended for developers with sound understanding of event-driven Javascript including SocketIO libraries.

Technical Overview

The following diagram describes the technical communication infrastructure between the Agent Manager and custom Agent Desk. The customers can send messages to the customized Agent Desk from multiple mediums (web browser, mobile app, and desktop).

The custom Agent Desk will communicate with the Agent Manager using REST APIs. A 3rd-party notification service, Firebase Cloud Messaging platform (FCM) will push the messages from Agent Manager to the custom Agent Desk. The customized Agent Desk should implement the APIs for receiving the notifications sent by FCM.
To listen to the events from Agent Manager, customized Agent Desk must implement the listener events. The message format will be SocketIO.

Assumptions and Constraints

The integration of mediums (web browser, mobile app, and desktop) with the Agent interface is left at the developer's discretion and not included in this guide.

Getting Started

- Establish the connection between Agent-interface and Agent Manager for the exchange of messages:

Agent Manager server URL - This is the URL that is used to make REST API calls and set up a SocketIO connection.
- REST API URL - https://{AGENT_MANANGER}/
- SockeIO URL - https://{AGENT_MANANGER}/

The details of the events are mentioned in Socket Events.

Use cases

The use cases for custom Agent Desk are explained in detail below:

1. Establish Connection with Agent Manager

To login to Agent Manager

For the agent to login to the Agent Manager, it is required to:

Initiate a post request to the agent manager as given in the User Login API in Postman. A successful response will provide the agent with the keyCloack user details.
Make the socket.io handshaking with the agent manager as given in the code block. The FQDN contains the agent-manager address and keycloak_User.
1. on successful creation of the connection, the socket library will receive a ‘connect’ event
2. on failure, the ‘connect_error’ event is received with the error details
  Note: The version of socket.io-client should be 4.4.0.

Agent Login

JS

import { io } from "socket.io-client";     let uri = {{FQDN}};     let origin = new URL(uri).origin;    let path = new URL(uri).pathname;     let socket = io(origin, {       path: path == "/" ? "" : path + "/socket.io",       auth: {         agent: {{keycloak_User}},         fcm: ""      }    });

After login with the agent manager, the agent will receive an event called ‘agentPresence’.

2. Change Agent States

a. To change parent state of agent

For changing the agent’s parent state, custom Agent Desk should emit the event called ‘changeAgentState’:

The ‘action’ parameter should be named ‘agentState’ and the ‘state.name’ parameter can have the possible values ‘READY’, ‘NOT_READY’, or ‘LOGOUT’
With the state ‘READY’ the reasonCode must be set to 'null' but for the state ‘LOGOUT’ and ‘NOT_READY’ the reasonCode can be set with some additional details as mentioned in the object but can be set to 'null' too.

b. To change MRD state of agent

For changing the agent’s mrd state, custom Agent Desk should emit the event called, ‘changeAgentState’:

The ‘action’ parameter should be named ‘agentMRDState’.

3. Agent Presence Event

On every request of changing the state, the Agent Manager will emit an event called, ‘agentPresence’:

The ‘action’ parameter in this object has two possible values

AGENT_STATE_CHANGED ⇒ When the state is successfully changed
AGENT_STATE_UNCHANGED => When the state can’t be changed at that time

NOTE: In order to set the MRD state ‘READY’, the Agent’s parent state should be ‘READY’ first and when the Agent’s parent state is set to ‘NOT_READY’ then all the MRD states would automatically be set to ‘NOT_READY’.

4. Push Mode Tasks

a. Request received by custom Agent Desk

Whenever there is a task request initiated from the routing engine, the custom Agent desk will receive an event called, ‘taskRequest’:

This task state is set to ‘RESERVED’ at that time for the agent and a RONA timer is initiated for that request.
If the task is accepted within the RONA time the task state is set to 'ACTIVE' else the task state is set to 'CLOSED' with reason RONA and the agent manager will emit the event ‘revokeTask’.

b. To accept a task

In order to accept the task, the custom Agent desk should emit an event called, ‘topicSubscription’:

On accepting the request, the agent manager will emit an event called, ‘onTopicData’ which contains all the possible information related to this conversation.

5. Emit Socket.io Events (Custom Agent Desk - Agent Manager)

Several types of events are emitted from Custom Agent Desk to Agent Manager and vice versa. The page Socket Events enlist all possible event types and their descriptions.

6. Emit CIM Events

There are two types of CIM Events that the Agent Desk must handle - Messages and System Events.

Exchange Messages in a Conversation

Whenever a message is sent by the agent or system activity is gene, the custom Agent desk should emit an event called, 'publishCimEvent’:

On accepting the request, the agent manager will emit an event called, ‘onCimEvent’.
Multiple types of messages should be supported by Agent Desk. The types of messages are described here in CIM Messages.

Reply to a Specific Message

In case of reply to any message in the conversation, the object "data" contains the ID of a previous message you are replying to. In case of a new message, a unique ID is generated.

For example:

publishCimEvent

JS

"data": {            
		"id": "142ad3a6-6ab8-4cf7-9553-959e2c3605c2" //reply to an existing message 
		"header": { ......... } 
		"body": { .............. } }

Handle System Events

Whenever a system activity takes place, the custom Agent desk should emit an event called, 'publishCimEvent’:

On accepting the request, the agent manager will emit an event called, ‘onCimEvent’.
There are several types of system activities to be handled. These activities are described here in CIM Events.

7. Reroute Chat Requests to Queues

An agent can request to reroute the chats to a specific queue in two cases:

a. Conference Request to Queue - whenever an agent wants to add another agent to the conference.

b. Transfer Request to Queue - whenever an agent wants to transfer the chat to another agent.

Conference Request to Queue

Whenever an agent wants to request another agent to the ongoing/active conversation and selects a specific queue from UI to make a conference request, the custom Agent Desk should emit an event called, 'directConferenceRequest':

the Routing Engine will choose an available agent (if any) and offer this request to that agent. Once the other agent accepts that request, that agent will become a participant in the conversation.
In case the other agent does not accept the request and RONA occurs, the Routing Engine will continue to find another available agent until TTL time expires.

Transfer Request to Queue

Whenever an agent wants to completely transfer the ongoing/active conversation to another agent and selects a specific queue from UI to make the transfer request, the custom Agent Desk should emit an event called, 'directTransferRequest':

after making the transfer request that agent will no longer be the part of that conversation. The Routing engine will choose an available agent (if any) and offer this request to that agent. If the other agent will accepts that request, that agent will also be the part of that conversation.
If the agent will not accept that request and RONA occurs Routing engine will continue to find another available agent until TTL time expires.

8. Silent Monitoring

Silent monitoring and bargin features are for supervisors. The pre-requisites are:

supervisors should have one or more assigned teams.
this feature is for push-mode and active chats only.
supervisor can only send Whisper Message as long as he is in silent monitoring role.

Whenever supervisors want to monitor any active conversation of any agent in their own teams, the custom agent desk should emit an event, 'JoinAsSilentMonitor'. On accepting the request, the agent manager will subscribe the supervisor to the conversation with the event called, ‘onTopicData’.

Barge In Feature

Whenever a supervisor wants to intervene in the on-going conversation instead of being a silent observer, the custom Agent Desk should emit an event, 'JoinAsBargin'.

The Agent Manager will emit an event, ‘onCimEvent’, updating the role of the supervisor as BargIn. Now the supervisor can send all types of CIM Messages along with whisper message.

9. Leave Conversation

In order to leave any joined conversation, the custom Agent desk should emit an event called, 'topicUnsubscription_' please ignore the underscore in the event name.

In response to this event, the agent manager will close the agent’s task associated with this conversation and emits an event ‘topicUnsubscription’ back to agent desk.