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