Documentation

Bot API

Using Bot API you can connect a chatbot to your account to process incoming chats. The events exchange works via the webhooks mechanism. The initiator of the exchange is JivoChat.

All events from JivoChat to the bot provider and back are sent as HTTPS requests using the POST method in application/json format. The request timeout is 3 seconds, with 2 retries until a regular successful response is received. If not, the chat is transferred to the agent. This gives bot-providers 9 seconds to update the software on the server which is enough in most cases.

Event types#

Message typeDirectionDescription
CLIENT_MESSAGEJivoChat API → Bot-ProviderNew client message event, that requires response options
BOT_MESSAGEBot-Provider → JivoChat APIBot's response to a client message
INVITE_AGENTBot-Provider → JivoChat APIChat transfer from a bot to an agent
AGENT_UNAVAILABLEJivoChat API → Bot-ProviderEvent, informing that no agents are available to accept the chat at the moment
CHAT_CLOSEDJivoChat API → Bot-ProviderChat closing event

CLIENT_MESSAGE#

This event is intended to transfer a client's message to the bot provider. The request with the message is processed, and the bot's response is sent into the chat.

Example

{ "id": "9661ab9c-48b0-11ed-a3d6-859398ff9bd9", "site_id": "123456", "client_id": "1233", "chat_id": "2037", "agents_online": true, "sender": { "id": 1233, "name": "John Smith", "url": "https://test.com", "has_contacts": true }, "message": { "type": "TEXT", "text": "Can you help me?", "timestamp": 1665415879 }, "channel": { "id": "12345678", "type": "widget" }, "event": "CLIENT_MESSAGE" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
site_idstringJivoChat account ID, to which a request belongs
client_idstringID of a client, who writes to one of the JivoChat channels Unique within the account
chat_idstringID of a chat, where conversation takes place Unique within the account
agents_onlinebooleanAgent status identifier (if the value is true, agents are online; false - agents are offline)
senderobjectInformation about the client
messageobjectInformation about the message that was sent
channelobjectInformation about the channel where the message was sent
eventstringEvent type

sender

НаименованиеТипОписание
idintID of a client (similar to client_id)
user_token optionalstringClient's ID sent using API-method
name optionalstringClient's name
urlstringURL of a page, from which a client sent a message
has_contactsbooleanInforms, whether a client has contacts details or not

message

NameTypeDescription
typestringMessage type
textstringMessage text
timestampintTime logging parameter

channel

NameTypeDescription
idstringID of the channel where the message was sent
typestringChannel type

BOT_MESSAGE#

This request type is used to transmit a bot response to a chat with a client. It is sent from bot provider to JivoChat endpoint.

Example

{ "id": "093e9c6a-48b6-11ed-907d-7d426317dad5", "client_id": "1235", "chat_id": "2041", "message": { "type": "BUTTONS", "title": "Would you like to make an order?", "text": "Would you like to make an order? Yes / No", "timestamp": 1583910736, "force_reply": true, "buttons": [ { "text": "Yes", "id": 1 }, { "text": "No", "id": 2 } ] }, "event": "BOT_MESSAGE" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
client_idstringID of a client, who writes to one of the JivoChat channels Unique within the account
chat_idstringID of a chat where conversation takes place Unique within the account
messageobjectBot message

Bot messages types#

1. TEXT#

Simple text message

  • Example
{ "message": { "type": "TEXT", "text": "Hello! How can I help you?", "timestamp": 1653127681833 }, }
NameTypeDescription
textstringMessage text
timestampintTime logging parameter, unix time

2. MARKDOWN#

Text message in Markdown format

  • Example
{ "message": { "type": "MARKDOWN", "content": "To disable **PUSH notifications** please follow the steps described in our [instructions](https://site.com/page_url)", "text": "To disable PUSH notifications please follow the steps described in our instructions https://site.com/page_url", "timestamp": 1583910736 }, }
NameTypeDescription
сontentstringMessage in Markdown format (the following styles are supported: link, bold, italic)
textstringText fallback for channels that don't support markdown format. If not specified, a message won't be sent to a client
timestampintTime logging parameter, unix time

3. BUTTONS#

  • Example
"message": { "type": "BUTTONS", "title": "Would you like to make an order?", "text": "Would you like to make an order? Yes / No", "force_reply": true, "buttons": [ { "text": "Yes", "id": 1 }, { "text": "No", "id": 2 } ], "timestamp": 1583910736, }
NameTypeDescription
titlestringText title for buttons
textstringText fallback for channels that don't support markdown format. If not specified, a message won't be sent to a client
force_reply optionalbooleanIf there is true value, the message input field is blocked, so a client chooses one of the suggested buttons
buttonsarraySet of buttons with canned replies
buttons.textstringCanned reply text
button.idstringID of a button, sent in chat

4. VIDEO, PHOTO#

The message format for these types is the same, the only difference is the type.

A file is transferred by passing a link to it.

  • Example
"message": { type: "VIDEO", file: "https://example.com/video.mp4", file_name: "video.mp4" file_size: 1583910736, thumb: "https://example.com/thumb.jpg" }
"message": { type: "PHOTO", file: "https://example.com/image.jpg", file_name: "image.jpg", text: 'Высылаю вам изображение', file_size: 1583910736, thumb: "https://example.com/thumb.jpg" }
NameTypeDescription
filestringURL to download the file (mandatory parameter)
file_namestringFile name
file_sizeintFile size, in bytes
textstringText attached to the message
thumbstringURL of the preview image

5. AUDIO, VOICE, DOCUMENT#

These are the same types as PHOTO and VIDEO, just without the preview image.

A file is transferred by passing a link to it.

  • Example
"message": { type: "AUDIO", file: "https://example.com/audio.mp3", file_name: "audio.mp3", file_size: 2048, }
"message": { type: "VOICE", file: "https://example.com/voice.mp3", file_name: "voice.mp3", text: 'Прикрепленный текст', file_size: 2048, }
"message": { type: "DOCUMENT", file: "https://example.com/document.pdf", file_name: "document.pdf", file_size: 2048, }
NameTypeDescription
filestringURL to download the file (mandatory parameter)
file_namestringFile name
file_sizeintFile size, in bytes
textstringText attached to the message

6. LOCATION#

  • Example
"message": { type: "LOCATION", latitude: 53.3416484, longitude: -6.2868531 }
NameTypeDescription
latitudefloatLatitude value (mandatory parameter)))
longitudefloatLongitude value (mandatory parameter)

INVITE_AGENT#

The event is sent from bot-provider to JivoChat if it is required to transfer a chat to an agent.

Example

{ "id": "123e4567-e89b-12d3-a456-426655440000", "client_id": "1234", "chat_id": "213123", "event": "INVITE_AGENT" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
client_idstringID of a client, who writes to one of the JivoChat channels Unique within the account
chat_idstringID of a chat where conversation takes place Unique within the client's account

AGENT_UNAVAILABLE#

The following event is sent from JivoChat to bot-provider in case if bot transfers a chat to agents and there are no agents online ready to accept a chat. After processing this request bot can continue communicating with a client, for example, it can request contacts from a user.

Example

{ "id": "f061d944-48bc-11ed-a11a-9b4e3e49df1b", "chat_id": "2043", "client_id": "1236", "event": "AGENT_UNAVAILABLE" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
client_idstringID of a client who writes to one of the channels Unique within the client's account
chat_idstringID of a chat where conversation takes place Unique within the account

CHAT_CLOSED#

This type of request is sent when an agent accepts a chat, or it is automatically closed by timeout. If bot provider receives this event, the bot will no longer be able to send messages to this chat.

Example

{ "id": "f9e59d98-48bc-11ed-896a-47ed16cbbd46", "chat_id": "2043", "client_id": "1236", "event": "CHAT_CLOSED" }

Event parameters

NameTypeDescription
idstringUnique event ID used for debugging
client_idstringID of a client who writes to one of the channels Unique within the client's account
chat_idstringID of a chat where conversation takes place Unique within the account

INIT_RATE#

The bot provider requests the display of a form to assess the quality of service in the chat.

Note that the score obtained by calling this method is not saved in JivoChat, but is transferred to the bot provider for storage and use.

{ "event": "INIT_RATE", "id": "123e4567-e89b-12d3-a456-426655440000", "client_id": "2", "chat_id": "4" }

Event Parameters

NameTypeDescription
idstringUnique event identifier, used for logging and debugging purposes
client_idstringIdentifier of the customer who writes to one of Jivo's channels Jivo unique within the account
chat_idstringIdentifier of the chat room where the dialog with the client will be entered unique within the account

CLIENT_RATED#

The client left an estimate in the form called by the INIT_RATE method.

Note that the score obtained by calling this method is not saved in Jivo, but is transferred to the bot provider for storage and use.

{ "id": "43d7b5de-d93c-11ed-ba4b-457f317d3806", "site_id": "540670", "client_id": "47454", "chat_id": "4", "agents_online": true, "sender": { "id": 47454, "name": "client_name" }, "rate": { "rating": "good", "comment": "Все было супер!", "timestamp": 1681308837 }, "channel": { "id": "1hjSGtiQ6e", "type": "widget" }, "event": "CLIENT_RATED", "options": null }
NameТypeDescription
idstringUnique event identifier, used for logging and debugging purposes
client_idstringIdentifier of the customer who writes to one of Jivo's channels unique within the account
chat_idstringIdentifier of the chat room in which the dialog with the client will be enteredunique within the account
agents_onlinebooleanAgent status indicator (online or offline)
senderobjectClient information: id - client_id (int), name - client name (string)
channelobjectInformation about the channel in which the message arrived: id - unique channel identifier (string), type - channel type (string)
rateobjectrating - rating given by the client with possible values: 'bad', 'badnormal', 'normal', 'goodnormal', 'good' (string); comment - comment to the rating (string)

The integration workflow and description of possible errors can be found in our help base article. In case of any questions please feel free to contact us by email info@jivochat.com or in chat.