Chat API

Tovie Platform provides a REST API for integrating your bot into third-party applications — the Chat API. Chats with bots can be implemented into external services, such as mobile apps, websites, or games.

Before using the Chat API, connect the Chat API channel to your project and obtain its token from the channel settings. The token is used in requests to all Chat API methods.

tip

For more information about methods, request parameters, response formats, returned errors, see Chat API specification.

API methods

Sending client requests to the chat

Sending client requests synchronously

The following methods are used to send requests from a client synchronously:

• POST /chatapi/{token}

  The method returns detailed information about the request, including cid.

  An optional cid property is a connection ID. This arbitrary string determines the current connection to the chat application. It can later be used for fetching events in the chat in order to filter out only those events which occurred during this connection.

• GET /chatapi/{token}

  A simplified method that returns several parameters of the request: clientId, query, and event.

tip

You can send either text queries or events in the chat application.

Sending client requests asynchronously

The POST /chatapi/{token}/async method allows you to send a client request or an event in the chat application asynchronously. Unlike the POST /chatapi/{token} method, you only get the message ID in response to the request. The rest of the information will be sent to a webhook, which you can specify in the Chat API channel settings.

The event will be sent to the webhook if:

• You have sent an asynchronous request.
• You have run a text campaign.
• A client have received a reply from an agent.
• A timeout between responses to the request is exceeded.

caution

If the request was not successful, the request will be resent three times. The timeout between responses for asynchronous requests is three seconds.

An array of JSON objects will be sent to the webhook:

{
    "token": "token",
    "clientId": "test",
    "questionId": "12345",
    "data": {
        "nlpClass": "/CatchAll",
        "confidence": -0.010999999999999979,
        "replies": [ // Bot message
            {
                "type": "text",
                "text": "Tell the bot something",
                "state": "/CatchAll"
            }
        ],
        "answer": "Tell the bot something",
        "newSessionStarted": false,
        "debugData": [],
        "endSession": false
    },
    "timestamp": "2022-09-28T12:32:13.262",
    "blockForm": false
}

Extending replies with custom fields

You can extend the bot’s response with custom fields. Use the $response object in the script:

state: Example
    script:
        $response.foo = "bar";

The foo field and other fields you set will be available in the bot’s response as fields nested in the data field.

Fetching asynchronous events in the chat

Via the GET /chatapi/{token}/events method, you can receive asynchronous events which occurred in the chat, such as:

• A response from an agent.
• A widget state change on another browser page.
• A client request sent on another page.
• A bot response to a request from another page.

caution

This method implements the long polling strategy: if no events are found, the method is blocked while waiting for the next event.

The method response length is limited to 250 messages. If you need to process more, use the method for fetching the chat message history instead.

Event filtering

This method accepts an all parameter which determines whether all events in the channel should be returned or agent replies only (the default behavior).

caution

If the client had several chats simultaneously and all events in the channel are returned, duplicate events may be returned if the cid parameter is not passed.

The ts parameter defines the time starting from which events should be filtered. When omitted, all events since the last request to the server are returned.

Fetching the chat message history

The GET /chatapi/{token}/client/{clientId}/history method allows receiving the message history with the client during the time specified time span or all time available.

Saving and loading the chat application state

The following methods allow saving and loading the chat application state during the conversation with the client:

• GET /chatapi/{token}/client/{clientId}/state
• POST /chatapi/{token}/client/{clientId}/state

tip

An arbitrary object is passed in the POST method request body. Subsequent requests to the GET method will return this object as is. Its contents are not checked.

Managing message statuses

You can track the status of messages that the bot has sent in the Chat API channel.

The following message statuses are supported in the Chat API:

Message status	Chat API
Sent	SENT
Delivered	DELIVERED
Read	READ
Not sent	NOT_SENT

Getting the message status

The GET /chatapi/{token}/client/{clientId}/message/{questionId}/status method allows you to get the status of the message.

Parameters:

• token — Chat API channel token. Go to Channels section, choose the Chat API channel and select  → Edit channel. Save the token.
• clientId — the client ID. You can find the ID in the Analytics section → Clients. Select the client and save their ID.
• questionId — the message ID. To get the ID, use the GET /chatapi/{token}/client/{clientId}/history method.

Updating the message status

The POST /chatapi/{token}/client/{clientId}/message/{questionId}/status method updates the status of the message. In the request body, specify a new value for the status field.

Updating statuses of several messages

The POST /chatapi/{token}/client/{clientId}/message-statuses method updates statuses of several messages. In the request body, specify the statuses field — an array of JSON objects.

Getting the number of unread messages

The GET /chatapi/{token}/client/{clientId}/message-not-read-count method allows you to know how many messages the client has not read.