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