Chat API

Tovie DialogStudio provides a Rest API for integration with third-party apps. For example, you can use it to implement a chat in a mobile app or a game.

tip

Rest API is a widespread way for transferring data to third-party services via HTTP requests.

The API allows chatting with either bots or agents.

Connecting the Chat API channel

1. Go to the Channels settings of your chatbot and choose Chat API.

   

2. Fill in the Channel name field.

3. You can leave the Bot token field empty, and Tovie DialogStudio will generate it for you.

4. Activate the Disable text input when using buttons toggle if you want to prevent clients from entering text messages when using buttons in the script.

5. Click Connect and wait for the Channel connected status.

Bot token

tip

The token you need for Chat API to work will be auto-generated.

To get it, click Copy token or open the channel settings and copy the token from the Token field.

Webhook for asynchronous requests

When working with the Chat API channel, you can use asynchronous requests and receive bot messages or events to a webhook address.

Asynchrony allows you to process several requests simultaneously. You can send new requests without waiting for the server to finish processing the previous ones. For example, with asynchronous requests, you can send text campaigns without delays and receive asynchronous events without additional requests.

To specify a webhook:

1. Select  in the Chat API channel bar.
2. Enter the URL in the Webhook URL field.

API methods

tip

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

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.
• 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
}

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.
• clientId — the client ID. You can find the ID in the Dialogs section. 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.