Agent API

Use Agent API to use human agent features and controls in a CRM application, a mobile app, or integrate with other agent channel applications such as MS Teams. A web-based agent gadget is shipped out of the box that can also be embedded in Cisco Finesse Agent/Supervisor desktop as a Finesse gadget.

Events

Here is the list of all possible events which can be used as a command sent to server and events received from the server. Origin of each event is specified by Source.

Event Name	Description
amq-sub	This event is used to subscribe to ActiveMQ topic.
amq-send	This event is used to send ActiveMQ related messages.
amq-msg	This event is used to receive a message from ActiveMQ
login	This event is used to login in the system
receiveChatRequest	The amq-msg event containing "head":"TaskAssigned" is used to show a chat request from a customer
joinConversation	This event is used to accept the chat request. Client needs to emit this event. Bot and customer also needs to emit this event to receive conversation updates.
changeState	To change the state client emit amq-send event with "head" : "AgentState" to change his state
addParticipant	This event is used to add a participant in the chat. Client needs to emit this event.
removeParticipant	This event is used to remove a participant from the chat. Client needs to emit this event.
transferChat	The transferChat event is used to transfer a chat from one agent to another agent/supervisor. Client needs to emit this event.
raiseHand	The raiseHand event is used to add the supervisor in the chat as a participant. Client needs to emit this event.
wrapUp	The wrapUp is used at the end of the conversation to upload wrapup data. Client needs to emit this event.
silentMonitor	The silentMonitor event is used by the supervisor to monitor any active conversation of some agent in his team. Client needs to emit this event.
bargeIn	The bargeIn event is used by the supervisor to join the conversation. Client needs to emit this event.
messageArrived	The messageArrived event is used to receive messages from other participants. Client needs to subscribe to this event.
conversationInfo	The conversationInfo event is used to receive complete details of the conversation
conversationList	The conversationList event is used to recieve all converrsations list, this is specific for the bot-connector
teamInfo	The teamInfo event is used to receive team members state, for supervisor user teamInfo also contains list of active chats against each team member
leaveConversation	This event is used to leave the conversation
endConversation	This event is used to end the conversation
RoleUpdated	The event is received once user role is changed.
getConversationInfo	The event is emitted on agent login

amq-sub

This request is used for an agent to subscribe on chat solution’s activemq.

Protocol	Websockets
Event Name	amq-sub
Source	Client
Input/Output Format	JSON
Request Payload	CODE `{ "AgentId": "abc", }`
Payload Parameters	AgentId: Id of the agent to login
Event Triggered

amq-send

For communication with media routing engine, chat solution uses activemq. Any message which needs to be passed to activemq is sent through amq-send event.

Protocol	Websockets
Event Name	amq-send
Source	Client
Input/Output Format	JSON
Request Payload	CODE `{ "head": "Login", }`
Payload Parameters	head: this is the JMS type of activemq message There will be other parameters of the request as well inside request payload.
Event Triggered

amq-msg

This event is used for sending activemq message data to the client.

Protocol	Websockets
Event Name	amq-msg
Source	Server
Input/Output Format	JSON
Request Payload	CODE `{ "head": "AgentInfo", }`
Payload Parameters	head: this is the JMS type of activemq message
Event Triggered

This request is used for an agent to login in chat solution.

Protocol	Websockets
Event Name	login
Source	Client
Input/Output Format	JSON
Request Payload	CODE `{ "agentId": "abc", "password":"*******", "mrd": "mrd-id" }`
Payload Parameters	agentId: Id of the agent to login Password: password of the agent Mrd:Id of the Mrd in which agent want to login
Event Triggered	messageArrived type: activityMessage

changeState

It allows the agent to change state between ready and not ready.

Protocol	Websockets
Event Name	amq-send
Source	Client
Input/Output Format	JSON
Request Payload	CODE `{ "head": "AgentState", "AgentId": "agentId", "State": "NOT_READY", "Mrd": "mrd-id", "ReasonCode": -1 }`
Payload Parameters	state: agent requested state
Event Triggered	amq-msg

receiveChatRequest

When agent is in ready state, receives a new chat request from customer,

Protocol	Websockets
Event Name	amq-msq
Source	server
Input/Output Format	JSON
Request Payload	CODE `{ "head": "TaskAssigned", "param": "param object", }`
Payload Parameters	param: Object of the param containing customer information and chatId
Event Triggered	messageArrived type: activityMessage

joinConversation

The agent can accept the chat request once receives a chat request. After accepting the chat request, chat will be started between agent and customer.

Protocol	Websockets
Event Name	joinConversation
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "conversationId": "abc333" }`
Payload Parameters	conversationId:
Event Triggered

addParticipant

Once the chat is active between agent and customer, the agent can add other available agents (agents in READY state) in the chat.

Protocol	Websockets
Event Name	addParticipant
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "participant": "participant object", "conversationId": "conversationId" }`
Payload Parameters	participant: participant object having participant information such as agentId etc. conversationId: Id of the conversation, in which participant is added
Event Triggered	messageArrived type:activityMessage activityType: participantAdded

removeParticipant

Agent, who first received the chat request from a customer is the owner of the conversation. If there are multiple participants in the conversation other than customer then an agent (owner of the chat) can remove any participant from the conversation other than the customer.

Protocol	Websockets
Event Name	removeParticipant
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "participantId": "participantId", "conversationId": "conversationId" }`
Payload Parameters	participantId: Id of the participant conversationId: Id of the conversation
Event Triggered	messageArrived type: activityMessage activityType: participantRemoved

transferChat

Once the agent has added other participants in the chat, he can transfer the chat to any of the participants (agents/supervisor).

Protocol	Websockets
Event Name	transferChat
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "participantId": "participantId", "conversationId": "conversationId" }`
Payload Parameters	participantId: Id of the participant conversationId: Id of current conversation
Event Triggered

raiseHand

During a chat, if an agent needs help, he can raise hand. By raising hand a chat request will be sent to his supervisor. Once the supervisor accepts the request, chat history will be visible to him and now he can help the agent.

Protocol	Websockets
Event Name	raiseHand
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "conversationId": "conversationId", "participantId": "supervisorId" }`
Payload Parameters	participantId: Id of the supervisor conversationId: Id of current conversation
Event Triggered

wrapUp

At the end of conversation with the customer, the agent can submit wrap-up.

Protocol	Websockets
Event Name	wrapUp
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "conversationId": "conversationId", }, "wrapup": "wrapup text",`
Payload Parameters	conversation: conversation object containing conversationId wrapup: wrapup reason text
Event Triggered

silentMonitor

The supervisor can see all active conversations of his team. He can select and monitor any of the active conversation but cannot participate in the conversation. This is called silent monitoring.

Protocol	Websockets
Event Name	silentMonitor
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "conversationId": "conversationId", }`
Payload Parameters	conversation: conversation object containing conversationId
Event Triggered

bargeIn

During silent monitoring, if supervisor wants to participate in the conversation, he will use bargeIn functionality. An activity message will be sent to the participants of the conversation other than the customer that supervisor has joined the conversation. Now the supervisor can send a message as well.

Protocol	Websockets
Event Name	bargeIn
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "conversationId": "conversationId", }`
Payload Parameters	conversation: conversation object containing conversationId
Event Triggered	messageArrived type: activityMessage activityType: participantJoined

conversationInfo

This event is received when customer/agent joins the conversation. It is also published on demand when agent emit getConversationInfo event

Protocol	Websockets
Event Name	conversationInfo
Source	server
Input/Output Format	JSON
Request Payload	CODE `{ "conversation": "conversation", "messages": "[]", "participant": "[]", "role": "<string>", "handRaise: "<boolean>" }`
Payload Parameters	conversation: conversation object containing conversation information messages: contains list of all the messages participant: list of participants role: role of the user in the conversation handRaise: state of the handRaise either true or false
Event Triggered	joinConversation

teamInfo

Whenever any agent in the team changes the state or logged in/logged out teamInfo event is published for the whole team.

Protocol	Websockets
Event Name	teamInfo
Source	server
Input/Output Format	JSON
Request Payload	CODE `{ "teamId": "teamId", "teamName": "teamName", "agents": "[]", "supervisors": "[]" }`
Payload Parameters	team: team object containing teamId,teamName,agents list and supervisors list agents and supervisor list contains objects of participant with id, name and state properties
Event Triggered

messageArrived

The messageArrived event is used to receive messages from other participant. Client need to subscribe to this event.

Protocol	Websockets
Event Name	messageArrived
Source	Server
Input/Output Format	JSON
Event Payload (for ChatMessage)	CODE `{ "conversationId": "7g5639ju987g", "type": "ChatMessage", "requestId":"99397bf7-a4fb-41c3-8292-a021b44262a6", "timestamp": "2018-05-07T06:52:21.661Z", "channel": "web", "from": { "id": "abcdedf", "name": "Kashif Sohail" }, "to": [ { "id": "yferdt5" }, { "id": "4ty678gu" } ], "text": "Hello, what is the status of my request", "attachments": [] }`
Payload Parameters	conversationId: The id of conversation to which message is being sent type: Type of message channel: The channel on which messaging
Event Triggered

leaveConversation

Once there are multiple agents in the conversation, any agent can leave the conversation

Protocol	Websockets
Event Name	leaveConversation
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "conversationId": "conversationId", "notify": "true" }`
Payload Parameters	converstionId: id of the converastion notify: a boolean, default is true,
Event Triggered	messageArrived type:activityMessage

endConversation

chat-owner has the rights to end the conversation, once endConversation events is received, conversation is ended for all the participants

Protocol	Websockets
Event Name	endConversation
Source	client
Input/Output Format	JSON
Request Payload	CODE `{ "conversationId": "conversationId", }`
Payload Parameters	converstionId: id of the converastion
Event Triggered	endConversation

RoleUpdated

This event is received whenever user role is changed.

Protocol	Websockets
Event Name	RoleUpdated
Source	server
Input/Output Format	JSON
Request Payload	CODE `{ "participantId": "agentId", "role": "<string>" "conversationId": "conversationId", }`
Payload Parameters	participantId: Id of the agent role: new role in the conversation converstionId: id of the converastion
Event Triggered

getConversationInfo

On login, agent emit this event to get all his conversations.

Protocol	Websockets
Event Name	getConversationInfo
Source	server
Input/Output Format	JSON
Request Payload	CODE `{ "AgentId": "agentId" }`
Payload Parameters	AgentId: Id of the agent
Event Triggered	conversationInfo

Schema

Participant Object

Defines a participant of the conversation and who can send or receive messages.

Property	Type	Description
displayName	String	Name of the participant to be displayed to other participants of the conversation
type	String	Type of participant. It can be Agent, Supervisor, Bot or Customer
Role	String	Role of the participant. Owner or Participant
status	String	Status of the participant. Ready, Active, Busy

Conversation Object

Defines a conversation which contains information of participants and messages being sent among participants.

Property	Type	Description
Id	String	The ID that identifies the conversation. The ID is unique per conversation. This conversationId is generated from service side and sent to the client when the client request initiate chat
type	String	Type of Message. ActivityMessage in this case
participants	Participant[]	Array of Participant objects.
activityType	String	Type of activity. One of these values: greetings, typing, participantAdded, participantRemoved, participantJoined, participantLeft, endOfConversation For details about activity types, see AcitivityTypes
messages	Message[]	List of messages exchanged in the current conversation.

Customer Object

Defines a customer which is also a participant of the conversation.

Property	Type	Description
displayName	String	Name of the participant to be displayed to other participants of the conversation
email	String	Email of the customer
phone	String	Phone number of the customer
channel	String	The channel on which messaging

Agent Object

Defines an agent who is a participant of the conversation.

Property	Type	Description
displayName	String	Name of the participant to be displayed to other participants of the conversation
type	String	Type of participant. In this case, it will be Agent.
role	String	Role of the participant. Owner or Participant
status	String	Status of the participant. Ready, Active, Busy
teams	Team[]	List of teams in which agent is the member
conversations	Conversation[]	List of active conversations.

Supervisor Object

Defines supervisor, he is also a participant of the conversation.

Property	Type	Description
displayName	String	Name of the participant to be displayed to other participants of the conversation
type	String	Type of participant. In this case, it will be Agent.
role	String	Role of the participant. Owner or Participant
status	String	Status of the participant. Ready, Active, Busy
team	Team	Supervisor’s team, in which his role is Supervisor

Team Object

Defines team, an agent and supervisor are always part of some team.

Property	Type	Description
id	String	Each team has always a unique identification.
name	String	Name of the team
members	Agent[]	Agents are added as members of the team. A team will consist of multiple agents
supervisors	Supervisor[]	List of supervisors. A team can have 1 or more supervisors

ActivityMessage object

Defines an activity message that is exchanged between server and client.

Property	Type	Description
conversationId	String	The ID that identifies the conversation. The ID is unique per conversation. This conversationId is generated from the service side and sent to the client when the client request initiate chat
type	String	Type of Message. ActivityMessage in this case
from	Participant	A Participant object that specifies the sender of the message
to	Participant[]	Array of Participant objects that specifies the recipients of the message. If the list is empty, the message will be broadcasted in the conversation.
activityType	String	Type of activity. One of these values: greetings, typing, participantAdded, participantRemoved, participantJoined, participantLeft, endOfConversation For details about activity types, see AcitivityTypes
info	Object	Notification data.

Events

​amq-sub

​amq-send

​amq-msg

​login

​changeState

​receiveChatRequest

​joinConversation

​addParticipant

​removeParticipant

​transferChat

​raiseHand

​wrapUp

​silentMonitor

​bargeIn