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 type | Direction | Description |
---|---|---|
CLIENT_MESSAGE | JivoChat API → Bot-Provider | New client message event, that requires response options |
BOT_MESSAGE | Bot-Provider → JivoChat API | Bot's response to a client message |
INVITE_AGENT | Bot-Provider → JivoChat API | Chat transfer from a bot to an agent |
AGENT_UNAVAILABLE | JivoChat API → Bot-Provider | Event, informing that no agents are available to accept the chat at the moment |
CHAT_CLOSED | JivoChat API → Bot-Provider | Chat 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
Name | Type | Description |
---|---|---|
id | string | Unique event ID used for debugging |
site_id | string | JivoChat account ID, to which a request belongs |
client_id | string | ID of a client, who writes to one of the JivoChat channels Unique within the account |
chat_id | string | ID of a chat, where conversation takes place Unique within the account |
agents_online | boolean | Agent status identifier (if the value is true, agents are online; false - agents are offline) |
sender | object | Information about the client |
message | object | Information about the message that was sent |
channel | object | Information about the channel where the message was sent |
event | string | Event type |
sender
Наименование | Тип | Описание |
---|---|---|
id | int | ID of a client (similar to client_id) |
user_token optional | string | Client's ID sent using API-method |
name optional | string | Client's name |
url | string | URL of a page, from which a client sent a message |
has_contacts | boolean | Informs, whether a client has contacts details or not |
message
Name | Type | Description |
---|---|---|
type | string | Message type |
text | string | Message text |
timestamp | int | Time logging parameter |
channel
Name | Type | Description |
---|---|---|
id | string | ID of the channel where the message was sent |
type | string | Channel 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
Name | Type | Description |
---|---|---|
id | string | Unique event ID used for debugging |
client_id | string | ID of a client, who writes to one of the JivoChat channels Unique within the account |
chat_id | string | ID of a chat where conversation takes place Unique within the account |
message | object | Bot message |
Bot messages types#
1. TEXT#
Simple text message
- Example
{ "message": { "type": "TEXT", "text": "Hello! How can I help you?", "timestamp": 1653127681833 }, }
Name | Type | Description |
---|---|---|
text | string | Message text |
timestamp | int | Time 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 }, }
Name | Type | Description |
---|---|---|
сontent | string | Message in Markdown format (the following styles are supported: link, bold, italic) |
text | string | Text fallback for channels that don't support markdown format. If not specified, a message won't be sent to a client |
timestamp | int | Time 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, }
Name | Type | Description |
---|---|---|
title | string | Text title for buttons |
text | string | Text fallback for channels that don't support markdown format. If not specified, a message won't be sent to a client |
force_reply optional | boolean | If there is true value, the message input field is blocked, so a client chooses one of the suggested buttons |
buttons | array | Set of buttons with canned replies |
buttons.text | string | Canned reply text |
button.id | string | ID 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" }
Name | Type | Description |
---|---|---|
file | string | URL to download the file (mandatory parameter) |
file_name | string | File name |
file_size | int | File size, in bytes |
text | string | Text attached to the message |
thumb | string | URL 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, }
Name | Type | Description |
---|---|---|
file | string | URL to download the file (mandatory parameter) |
file_name | string | File name |
file_size | int | File size, in bytes |
text | string | Text attached to the message |
6. LOCATION#
- Example
"message": { type: "LOCATION", latitude: 53.3416484, longitude: -6.2868531 }
Name | Type | Description |
---|---|---|
latitude | float | Latitude value (mandatory parameter))) |
longitude | float | Longitude 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
Name | Type | Description |
---|---|---|
id | string | Unique event ID used for debugging |
client_id | string | ID of a client, who writes to one of the JivoChat channels Unique within the account |
chat_id | string | ID 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
Name | Type | Description |
---|---|---|
id | string | Unique event ID used for debugging |
client_id | string | ID of a client who writes to one of the channels Unique within the client's account |
chat_id | string | ID 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
Name | Type | Description |
---|---|---|
id | string | Unique event ID used for debugging |
client_id | string | ID of a client who writes to one of the channels Unique within the client's account |
chat_id | string | ID 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
Name | Type | Description |
---|---|---|
id | string | Unique event identifier, used for logging and debugging purposes |
client_id | string | Identifier of the customer who writes to one of Jivo's channels Jivo unique within the account |
chat_id | string | Identifier 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 | Тype | Description |
---|---|---|
id | string | Unique event identifier, used for logging and debugging purposes |
client_id | string | Identifier of the customer who writes to one of Jivo's channels unique within the account |
chat_id | string | Identifier of the chat room in which the dialog with the client will be enteredunique within the account |
agents_online | boolean | Agent status indicator (online or offline) |
sender | object | Client information: id - client_id (int), name - client name (string) |
channel | object | Information about the channel in which the message arrived: id - unique channel identifier (string), type - channel type (string) |
rate | object | rating - 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.