Realtime Messaging API
This document describes the realtime 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 the channelId
refers to the id of the channel that can be retrieved through the user interface. Interaction with the realtime messaging API proceeds by first registering the enduser with it's 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 this endpoint. This endpoint can be invoked whenever the data for the user changes.
The endpoint to update user data is
/users/<userId>
The following JSON 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 (waiting for the answer) fashion is done using the
/messages/
endpoint. 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 on the
/messages/USERID/history
endpoint 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 retriaval of recent messages. The endpoint for message polling is:
/messages/<userId>/
and responds with a MessageResponse (see Models section).
Sending Channel Events as a User
Sending channel events in a synchronous (waiting for the answer) fashion is done using
/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
Is returned from all methods concerning message sending and retrieval. The response consists of a flag that indicates whether followup 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"
}
]
}