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.
on successful creation of the connection, the socket library will receive a ‘connect’ event
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
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
"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.