Chat API

Aimylogic 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.

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 Aimylogic 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

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.

API methods

A detailed description of the Chat API: methods, request parameters, response formats, examples, returned errors

Sending client requests to the chat

The following methods are used to send requests from the client:

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

Connection ID

The body of requests to POST /chatapi/{token} can contain an optional cid property – an arbitrary string which determines the current connection to the chat application.

This string can later be used for fetching events in the chat in order to filter out only those events which occurred during this connection.

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.

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 events than that, 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).

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:

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.