Web Channel API

Web Frontend Connector

Das WEB Frontend präsentiert sich nach außen hin als normale REST API und nicht wie die anderen Kanäle als Webhook.

API

webchat.mercury.ai/CHANNELID/users POST: create user GET : get user by id

CHANNELID ist immer die automatisch generierte ID des Kanals in Form eines langes Base64 kodierten Tokens.

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 USERID: the client side ID of the user, can be any string that is unique for that particular user The following JSON can be POSTed:

{
    "firstName" : "Vorname",
    "lastName" : "Nachname",
    "locale" : "DE_de"
}

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 the .../events/ endpoint. 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"
        }
    ]
}