| Table of Contents |
|---|
Summary
LiveAgents mediator acts as a middleware and allows forwarding an user from a conversation with an automated bot to a live chat with a real agent.
This mediator has been designed to receive and send messages from the final user to the agent and viceversa, and its not linked to an specific channel.
Architecture
In order to establish a conversation with a live agent, the user must be placed in the queue and wait for an agent to take the conversation. Once these steps has been completed, messages will flow between the user and the agent through the middleware.
...
Each user message should be delivered as a new request to the corresponding endpoint from the mediator including the required parameters so it can be correctly delivered to the agent. In the other hand, messages coming from the agent to the user, will be delivered to the bot building platform (e.g. RapidPro) by using its API. Since the API will be used for delivering messages, the LiveAgents Mediator MUST know the corresponding credential to establish the correct communication and perform the needed requests. These credentials will be stored safely in the mediator.
...
...
Rapid Pro integration
Rocket Chat integration
Register clients into Rocket Chat
Receive messages from Rocket Chat Agent
Receive messages from Rapid Pro client
Limitations
Agents from Rocket Chat can not:
Send emojis
Send messages greater than 640 characters
Send media data such as videos, images or audios
Edit a message in the chat, instead, a new message will be sent
Client from Rapid Pro can not:
Send media data such as videos, images or audios
Send reactions given to an agent message.
End points & examples
POSTMAN DOCUMENTATION
https://documenter.getpostman.com/view/25775499/2s93RMVvtL
API usage
For the live agents API to work as expected, is needed to follow certain order in the API calls.
POST - live-agents/registerClient
The first endpoint that should be called is /live-agents/registerClient as POST request. This API call will send the client request to Rocket Chat to be attended by an Agent.
The body should have the following parameters:
| Code Block |
|---|
{
"contact": {
"name": "",
"uuid": ""
},
"department": "",
"results": {},
} |
| Info |
|---|
The uuid can be accessed via the Rapid Pro API, especifically from the Contacts Endpoint: Rapid Pro Contacts Endpoint. Please refer to that documentation in case you need to know some values required by the Live Agents API. |
...
Object name
...
Keys
...
Value type
...
Description
contact
...
name
...
string
...
Contact name to be displayed on Rocket Chat contact information column.
...
uuid
...
string
...
Uuid refers to a unique identifier to the contact registered in Rapid Pro. This is used for Rapid Pro to know where message will be sent.
...
department
...
string
...
Deparment is the actual ‘department’ created on Rocket Chat to receive messages.
...
results
...
empty object
...
Results is an object used in Rapid Pro to store its local variables and values. With this parameter, live agents will be able to catch some messages sent by the client.
POST - /live-agents/sendMessageToClient
The second endpoint that should be called is /live-agents/sendMessageToClient as POST request. This API call will send a message from Rocket Chat Agent to the client. This step needs to be done BEFORE sending a message from the client to the agent, so the service can update the room id where the messages from the client are going to be sent.
| Info |
|---|
This API call does not need to be done as second step if Rocket Chat has in the omnichannel webhook option the ‘Chats in queue’ enabled. This is because ‘Chats in queue’ sends in background a request to the service and updates the room id, in that case, no message would be received but the client can now send messages to the chat even if the chat is not taken. |
| Code Block |
|---|
{
"_id": "",
"visitor": {
"token": "",
"name": "",
"email": "",
"phone": "",
},
"agent": {
"name": ""
},
"type": "",
"messages": [
{
"msg": ""
}
]
} |
...
Object name
...
Keys
...
Value type
...
Description
...
_id
...
string
...
This id refers to the room id for the chat session in rocket chat. This ID is shown in the chat url : http://rocketchat.psi-mis.org/live/2q4FnH8mnrizF2iBT/room-info
...
visitor
...
token
...
string
...
Token is the actual rapid pro contact UUID. With this, rapid pro would know where and to who the message will be sent.
...
name
...
string
...
Name of the client.
...
...
string
...
Email of the client.
...
phone
...
string
...
Phone of the client.
...
agent
...
name
...
string
...
Name of the agent.
...
type
...
string
...
Type refers to the “type” of operation that roket chat is doing. There are 3 types of operations supported by the live agents service:
LivechatSessionQueuedLivechatSessionMessageLivechatSessionQueued
If the request has by type “LivechatSessionTaken" “LivechatSession", the live agents service will send to the client a message saying “You are now being attended by: [agent name]
If the request has by type “Message" live agents service will take the request message and redirect that message to rapid pro.
If the request has by type “LivechatSessionQueued" live agents service will NOT send a message to the client but will update the roomID for the session between the client and the agent.
...
messages
...
msg
...
string
...
Message to be sent to the client.
POST - live-agents/sendMessageToAgent
The third endpoint that should be called is /live-agents/sendMessageToAgent as POST request. This API call will send a message from the client to the Rocket Chat agent. This steps is the last one as you already have a chat in the Rocket Chat queue and also a room ID registered in the service. Now you can have a conversation between the two agent/client.
| Code Block |
|---|
{
"contact": {
"name": "",
"uuid": ""
},
"department": "",
"results": {
"clientmessage": {
"value": ""
}
},
} |
| Info |
|---|
The request provided for the endpoint is similar to live-agents/registerClient. Now, we are sending “clientmessage” that is the actual message received from rapid pro flow. |
...
Object name
...
Keys
...
Value type
...
Description
contact
...
name
...
string
...
Contact name to be displayed on Rocket Chat contact information column.
...
uuid
...
string
...
Uuid refers to a unique identifier to the contact registered in Rapid Pro. This is used to actually send message for the user instead of the URN.
...
department
...
string
...
Deparment is the actual ‘department’ created on Rocket Chat to receive messages.
...
results > clientmessage
...
value
...
string
...
Results is an object used in Rapid Pro to store its local variables and values. With this parameter, live agents will be able to catch some messages sent by the client. For this endpoint “clientmessage” is provided, so the service can send a text to Rocket Chat room.