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"
        }
    ]
}