API Usage

Live Agents Mediator API allows a user to register clients into a communication platform and allows the communication between a channel (facebook) and the communication platform where the client was registered (RocketChat). Check postman documentation here: Live Agents

Page Content:

1 POST - live-agents/registerClient
- 1.1 Request Body
- 1.2 Response
2 POST - /live-agents/sendMessageToClient
- 2.1 RequestBody
  - 2.1.1 Request Body for Attachments
- 2.2 Response
3 POST - live-agents/sendMessageToAgent
- 3.1 Parameters
- 3.2 Response
4 GET - /live-agents/project/{projectName}/country/{countrycode}/day-status
- 4.1 Parameters
- 4.2 Response
5 DELETE - /live-agents/session/user/{userid}
- 5.1 Parameters
- 5.2 Response

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.

This endpoint requires the user to be in an available working day/hour. Please, check more information about this validation here: Day Status

Request Body

{
    "contact": {
        "name": "", // OPTIONAL
        "uuid": "",
        "urn":"", //OPTIONAL
        "mongoid":"" // OPTIONAL
    },
    "department": "",
    "results": {},
}

Object name	Keys	Value type	Description

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. This uuid has some use cases: The service use it to search clients by this unique identifier (no endpoint exposed). It can be used to send API requests to RapidPro. This means, no facebook configuration is set up and the service relies only in RapidPro to handle all the communication between services.
	Under consideration recent conversation	string/ array ?	The last 10 or 20 interchanges between the bot and the user, to be re-posted to the agent that takes the conversation in RocketChat, to give context to the user request. Format: whatever RapidPro provides?
	urn	string	The URN represents the channel joined with the ID of the client for that Channel. E.g: facebook:123456 refers that the communication channel is facebook and that the client id for that facebook page is 123456.
department		string	Department 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.

In case the uuid is from RapidPro, it 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.

Response

{
    "status_code": 200,
    "status": "success",
    "msg": "success"
}

Keys	Value type	Description

Keys	Value type	Description
status_code	integer	Status code for internal process in service.
status	string	Status code in a string representation.
msg	string	Message for the status provided. Shows more details on what might have happened in error cases.

POST - /live-agents/sendMessageToClient

SendMessageToClient endpoint allows sending a message from the Communication Platform (RocketChat) to a Channel (Facebook).

This endpoint works only if a user/customer is already registered in the Communication Plaftform. Otherwise, the service would not be able to find the user and the channel where the message is supposed to be sent.

RequestBody

SendMessageToClient endpoint allows users to send a message or an attachment to a client:

{
  "visitor": {
    "token": "", 
  },
  "type": "",
  "messages": [
    {
      "msg": ""
    }
  ]
}

Object name	Keys	Value type	Description

Object name

Keys

Value type

Description

visitor

token

string

Token is the actual RapidPro contact UUID. With this, rapid pro would know where and to who the message will be sent.

type

string

Type refers to the “type” of operation that RocketChat is doing. There are 3 types of operations supported by the live agents service:

LivechatSessionQueued
LivechatSession
Message
LivechatSessionQueued

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 type “Message" live agents service will take the request message and redirect that message to the Channel associated to the Customer.

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. If type of operation is “Message”, the property “msg” needs to be included, otherwise the API won’t throw an error.

Request Body for Attachments

Sends an attachment to the client.

Object name	Keys	Value type	Description

Object name	Keys	Value type	Description
visitor	token	string	Token is the actual RapidPro contact UUID. With this, rapid pro would know where and to who the message will be sent.
type		string	Type refers to the “type” of operation that RocketChat is doing. There are 3 types of operations supported by the live agents service: `LivechatSessionQueued` `LivechatSession` `Message` `LivechatSessionQueued` 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	fileUpload	publicFilePath	URL where the image is hosted.
messages	fileUpload	type	Type of the multimedia to be sent. The supported types are: Image/PNG Image/JPG Image/GIF Video/MP4 Video/AVI Video/OGG

Response

Keys	Value type	Description

Keys	Value type	Description
status_code	integer	Status code for internal process in service.
status	string	Status code in a string representation.
msg	string	Message for the status provided. Shows more details on what might have happened in error cases.

POST - live-agents/sendMessageToAgent

SendMessageToagent endpoint sends a message to a user in the Communication Platform (RocketChat.

Parameters

SendMessageToAgent endpoint allows clients to send a message or an attachment to an agent:

Object name	Keys	Value type	Description

Object name	Keys	Value type	Description
contact	name	string	Contact name to be displayed on Rocket Chat contact information column.
contact	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.
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.

Response

Keys	Value type	Description

Keys	Value type	Description
status_code	integer	Status code for internal process in service.
status	string	Status code in a string representation.
msg	string	Message for the status provided. Shows more details on what might have happened in error cases.

GET - /live-agents/project/{projectName}/country/{countrycode}/day-status

Country day status endpoint provides the capability to look if the current day and hour is an operation hour for business. This means that if the current day and hour is not available, the API returns a property indicating this. Please, check more information about this endpoint here: Day Status

Parameters

Specifies which project’s information is needed to be retrieved. At the moment, two values are possible to retrieve:

fp
hiv

Specifies which country’s information is needed to be retrieved, this country code MUST provided in 2 letter format (Guatemala: gt, Panama: pa, Honduras: hn, El Salvador: sv…).

Response

Keys	Value type	Description

Keys	Value type	Description
time_zone	string	Contact name to be displayed on Rocket Chat contact information column.
start_date	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.
end_date	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.
start_time	string	Starting time for working/holiday
end_time	string	Ending time for working/holiday
is_registration_available	boolean	Availability for users to register on the communication platform
day_type	string	What type of day is found for the current day: holiday or workingday
day_name	string	Name of the found day: working days: “monday”, … , “friday” holidays: “Semana Santa”, “Navidad
message	string	Predefined message to be sent to the user reporting that the current day is not available for registration

DELETE - /live-agents/session/user/{userid}

Delete user session endpoint allows to close a conversation in the Communication Platform (RocketChat) and delete any user session data stored in live agents service.

Parameters

Specifies which user session is needed to be deleted. As the current flow comes from RocketChat, the user id is the token generated from RapidPro, this id is the one to be used in the Register Client Endpoint

Response

Keys	Value type	Description

Keys	Value type	Description
status_code	integer	Status code for internal process in service.
status	string	Status code in a string representation.
msg	string	Message for the status provided. Shows more details on what might have happened in error cases.

Platform 2.0

API Usage

POST - live-agents/registerClient

Request Body

Response

POST - /live-agents/sendMessageToClient

RequestBody

Request Body for Attachments

Response

POST - live-agents/sendMessageToAgent

Parameters

Response

GET - /live-agents/project/{projectName}/country/{countrycode}/day-status

Parameters

Response

DELETE - /live-agents/session/user/{userid}

Parameters

Response

Related content