Real-time messaging API
This document describes the real-time messaging API, which is intended to be used to connect your Mercury.ai assistant to a smartphone app or to connect your assistant to novel yet unsupported channels.
API
The base URL for this API is:
htpps://webchat.mercury.ai/<channelId>/
Where channelId
refers to the ID of the channel that can be retrieved through the user interface. Interaction with the real-time messaging API proceeds by first registering the end user with their name and locale. This allows your assistant to correctly address the user.
Updating user data
New users should be introduced before they start sending messages. Users can be introduced by updating their data using the following endpoint:
/users/<userId>
It can be invoked whenever the data for the user changes.
The following JSON body can be POSTed:
{
"firstName" : "First Name",
"lastName" : "Last Name",
"locale" : "DE_de"
}
Parameter | Description |
---|---|
userId | the client side ID of the user, can be any string that is unique for that particular user |
firstName | the user`s first name |
lastName | the user`s last name |
locale | sets the user`s language and locale |
Sending messages as a user
Sending messages in a synchronous fashion (i.e. waiting for the answer) is done using the following endpoint:
/messages/
The endpoint accepts send message requests in the following format:
{
"fromUserId" : "ID of a user that was previously introduced to the /users/ID endpoint",
"message" : {
A message in the Mercury message format
}
}
The endpoint responds with a MessageResponse
(see Models section).
Retrieving previous messages
Previous messages for a user can be retrieved with a GET request to the following endpoint:
/messages/<userId>/history
Using the following parameters:
Parameter | Description |
---|---|
referenceId | The id of the message that serves as the reference point to retrieve older messages |
count | Number of historic messages to retrieve |
The endpoint responds with a MessageResponse
(see Models section).
Polling for new messages
Polling for new messages follows a similar specification as retrieving previous messages, except that no count of messages can be given as this endpoint is only for the retrieval of recent messages. The endpoint for message polling is:
/messages/<userId>/
It responds with a MessageResponse
(see Models section).
Sending channel events as a user
Sending channel events in a synchronous fashion (i.e. waiting for the answer) is done using the following endpoint:
/events/
The endpoint accepts requests in the following format:
{
"fromUserId" : "ID of a user that was previously introduced to the /users/ID endpoint",
"eventId" : "UUID that allows to track the event through the platform",
"event" : {
An event in the Mercury channel events format
}
}
The endpoint responds with a MessageResponse
(see Models section).
Models
Generic models used as responses.
MessageResponse
A MessageResponse
is returned from all methods concerning message sending and retrieval. The response consists of a flag that indicates whether follow-up messages are to be expected, which on the frontend side could reflect in a typing indicator being shown.
{
"is_typing": "boolean",
"data" : [
MessageModel, ...
]
}
Message model
Each individual message is represented as follows:
{
"originType" : "BOT or HANDOVER",
"fromUserId" : "The client side userId",
"timestamp" : "Milliseconds since epoch",
"message" : "Message in mercury format"
}
Event model
Each individual event is represented as follows
{
"name" : "Name of the event",
"timestamp" : "Milliseconds since epoch",
"payload" : "Bot specific event payload json"
}
Errors
In case of errors the API returns a special JSON in the following format:
{
"errors" : [
{
"code": "error code",
"message": "error message"
}
]
}