Graphlogic.ai documentation

Messaging API

Chat API

Chat API is a generic channel with a public API designed to enable the

@Agent⁠

to connect to

@End Channel⁠

s for which there is no built-in connector within the

@Platform⁠

. You can organize such a generic channel using Chat API Generic Connector.

Connecting

Configuring an Agent channel in the Platform

You need to create and configure an

@Project Channel⁠

with the “Chat API” connector.

Click on the agent settings button.

⁠

Click the Add channel button.

⁠

The

@End Channel⁠

selection panel will open.

⁠

Select

@Chat API⁠

The

@Project Channel⁠

creation panel will open.

⁠

Optionally, enter a title for this

@Project Channel⁠

in the Name field with the placeholder New channel.

⁠

Enter the address of your server in the Channel webhook URL field as https://{server_address}, where {server_address} is the address of the

@Platform⁠

⁠

Important: The specified method will be appended to the address when sending a response by the
@Agent⁠
to a request from the client's channel/server: https://your_company.com/send_message*.*

If necessary, set the token in the Channel token field.

⁠

Important: The token should be specified if the client-side authentication is done through the header. More details are described in
Authorization on the client side⁠
.

Copy the webhook link for the agent channel (Chatbot webhook URL) by clicking the Copy this webhook button.

⁠

To save the

@Project Channel⁠

without activating it, click the CREATE button.

⁠

To save and activate the

@Project Channel⁠

, click the CREATE & ACTIVATE button.

⁠

The

@Project Channel⁠

will be saved and activated if:

The

@Agent⁠

is trained;

The token in the Channel token field is unique (there are no active channels of the same type with the same token);

The channel address is accessible;

The channel webhook is registered succesfully.

The

@Project Channel⁠

will be saved but not activated if one or more conditions are not met.

To cancel

@Project Channel⁠

creation, click the CANCEL button.

⁠

Editing and Deleting Agent Channel

To edit an

@Project Channel⁠

, click on its icon on the

@Agent⁠

card.

⁠

To edit any field, click the field and enter a new value.

To apply changes to an activated

@Project Channel⁠

, click the APPLY button.

⁠

Changes will be applied if:

The

@Agent⁠

is trained;

The token in the Channel token field is unique (there are no active channels of the same type with the same token);

The channel address is accessible;

The channel webhook is registered succesfully.

Changes will not be applied if one or more conditions are not met.

To deactivate the

@Project Channel⁠

, click the DEACTIVATE button.

⁠

To apply changes to a non-activated

@Project Channel⁠

, click the SAVE button.

⁠

To apply changes and activate the

@Project Channel⁠

, click the SAVE & ACTIVATE button.

⁠

Changes will be applied and the

@Project Channel⁠

will be activated if:

The

@Agent⁠

is trained;

The token in the Channel token field is unique (there are no active channels of the same type with the same token);

The channel address is accessible;

The channel webhook can be registered.

Changes will be applied but the

@Project Channel⁠

will not be activated if one or more conditions are not met.

To cancel making changes, click the CANCEL button.

⁠

To delete the

@Project Channel⁠

, click the DELETE button.

⁠

Requests from the client channel/server to the Agent

Method:

HTTPS, POST with content-type JSON

API Endpoint for receiving requests by

@Project Channel⁠

Chatbot webhook URL specified while connecting the to accept requests.

Endpoint format (Chatbot webhook URL):

Cloud

https://{server_address}/connector/chatapi/chatapi_message/{token}/bot_api_webhook

On-Premises

https://{server_address}/connector/chatapi/chatapi_message/bot_api_webhook

Where:

{server_address} —

@Platform⁠

address,

{token} — token.

Request structure

Request body structure:

{

"event": (string),

"chat_id": (string),

"visitor"(optional object): {

"id": (string),

"fields": {

Fields (object)

}

"message": {

Message (object)

"service_data"(optional object): {

Service data (object)

}

Important: The structure of the Message object depends on the type of message being transmitted (text, file, button click) and can consist of different types of data and fields.

Event type

Event is the type of event subjected to processing by the

@Agent⁠

according to a certain logic.

Supported events:

new_message — an event transmitted to the

@Agent⁠

by the client channel/server containing a

@Bot user’s Message⁠

Chat_id identifier

chat_id is a

@Chat⁠

@Dialog⁠

@Bot User⁠

identifier on the client side (in the social app known as the final channel), is the base for creating a

@Chat⁠

with this

@Bot User⁠

on the

@Platform⁠

Visitor Object

Visitor is an optional object that contains info about the

@Bot User⁠

Visitor format:

{

"id": (string — user ID pseudo-unique, assigned by the client's server),

"fields": {

"name": (string),

"login": (string),

"phone": (string),

"email": (string),

"site": (string)

}

Visitor example:

{

"id": "03e1c040d8214bfa8ccfbb053186a24a",

"fields": {

"name": "Mike",

"login": "mike",

"phone": "+18891111111",

"email": "mike@gmail.com",

"site": "https://site.com"

}

Message object

Message is an object containing information sent to the

@Agent⁠

for processing.

{

"kind": (string — message type),

"text": (string — message text),

"data": (JSON — file or button clicked data)

}

Supported content types

Below are examples of the contents of the Message object for different types of messages.

Text

Message format:

{

"kind": "text",

"text": (string — message text)

}

File

Message format:

{

"kind": "attachment",

"attachment": {

"id": (string — file id),

"content_type": (string — Internet Media Type),

"url": (string — file URL)

}

If kind == attachment then Public Chat API gets file data and converts it into a text message for the

@Agent⁠

in the following format: file:{file_type}|{file_id}|{file_url} . The file is not downloaded by the

@Agent⁠

Service data object

Service data is any object containing custom data sent to the

@Agent⁠

for processing (e.g. for using this data in the

@Dialog⁠

). Optional object.

Button Clicking

Message format:

{

"kind": "keyboard_response",

"keyboard_response": {

"button": {

"id": (string — button id),

"text": (string — button label)

}

Responding to requests from the client channel/server to the Agent on the Platform

⁠
`@Platform`⁠
response on successful request

HTTP status: 200 OK

BODY:

{

"result": "ok"

}

⁠
`@Platform`⁠
response on failed request

The

@Project Channel⁠

is inactive or there is an error in the Chatbot webhook token in the URL:

HTTP status: 400 Bad Request

BODY:

{

"error": "There is no active channel for received event."

}

Missing requirement parameter in request body

HTTP status: 400 Bad Request

Incorrect URL

HTTP status: 404: Not Found

Incorrect JSON request body: invalid event or kind parameter

HTTP status: 200 OK

Requests from Platform to Client Channel/Server

Below are the formats, examples and descriptions of requests from the Public Chat API to the client server.

Basic URL

Requests are sent to the URL of the client server entered in the Channel Webhook : URL when connecting the

@Project Channel⁠

URL format: https://{server_address}/{method}, where:

{server_address} —

@Platform⁠

address,

{method} — a method of the Public Chat API.

Methods of the Public Chat API:

/send_message — sending a message by the

@Agent⁠

to the

@Bot User⁠

/close_chat — sending an event to close the

@Dialog⁠

Authorization on the client side

Authorization can be performed via:

Unique URL.

Specify the URL containing the token in the Channel webhook: URL field when connecting the

@Project Channel⁠

. The Channel webhook: Token field is not to be filled in:

Header

Specify the authorization token in the Channel webhook: Token field when connecting

@Project Channel⁠

. The token from the Channel webhook: Token field will be substituted in the header by default.

Authorization format when using a token:

Authorization: Token {token}

Example of authorization:

Authorization: Token ac650a3c369a4b9599ad52ab71943712

General structure of request

Method: /send_message

Type of request: POST

Content-type: application/json

Query-string parameters: not required

URL format in case the

@Agent⁠

sends a message to the visitor:

https://{server_address}/send_message

where {server_address} is

@Platform⁠

address.

Request body format:

{

"message": Message (object),

"chat_id": (string)

}

Important: The structure of the Message object depends on the type of message being transmitted (text, file, buttons).

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.

Chat API

Connecting

Configuring an Agent channel in the Platform

Editing and Deleting Agent Channel

Requests from the client channel/server to the Agent

Request structure

Event type

Chat_id identifier

Visitor Object

Message object

Supported content types

Responding to requests from the client channel/server to the Agent on the Platform

⁠@Platform⁠ response on successful request

⁠@Platform⁠ response on failed request

Requests from Platform to Client Channel/Server

Basic URL

Authorization on the client side

General structure of request

⁠
`@Platform`⁠
response on successful request

⁠
`@Platform`⁠
response on failed request