Bot API
Our Bot API allows you to connect bot platforms to any conversations in JivoChat: chat on the website, instant messages, and social networks. When adding a bot, all conversations will first be sent to the bot provider for processing.
If you have your own bot on any platform and you would like to connect it to us, please send us an email to generate your provider ID.
Data exchange
The initiator of the exchange is JivoChat. This happens when there's an incoming message from a client. Events are exchanged with bot providers using the webhooks mechanism. All events from JivoChat are sent to the endpoint of the provider and, in response, the provider sends events to JivoChat's endpoint.
All events from JivoChat to and from the bot provider are sent as HTTPS requests using the POST method in application/JSON format. The request timeout is 3 seconds, and the number of retries is 2 until a regular successful response is received, otherwise, the client is transferred to the agent. This gives 9 seconds to update the software on the server, which is enough in most cases.
The endpoint URL of the bot provider is formed at its discretion. JivoChat's endpoint is configured as follows: bot.jivosite.com/webhooks/{provider_id}, where provider_id is a unique provider identifier, issued for each provider separately.
Response codes#
The table below lists the possible response codes from JivoChat and the bot provider.
Response codes | Description |
---|---|
200 OK | Successful, regular response |
400 Bad Request | Invalid request format. You must check the request fields for compliance with the API format |
401 Unauthorized | Authorization error |
403 Forbidden | Access denied |
404 Not Found | Incorrectly formed endpoint |
405 Method Not Allowed | This method or event is not supported |
429 Too Many Request | Exceeded requests per unit time |
500 Internal Server Error | Request processing error |
502 Bad Gateway | Server is overloaded |
503 Service Unavailable | Server is not available |
504 Gateway Timeout | Failed to perform request |
In the event of an emergency, it is recommended that information about the error be transmitted to the response body in the following format:
{
"error" :
{
"code": "<error code>",
"message": "<human-readable error message>"
}
}
Error codes#
Code | Description |
---|---|
invalid_client | Token client authentication error. Returned with HTTP code 401 Unauthorized |
unauthorized_client | Authorization failed by header Authorization |
invalid_request | The request does not contain a required parameter, an unsupported parameter value is being used, a duplicate of the parameter is contained, several sets of credentials are included, or other request errors |
Authentication#
The authentication of the client of the bot provider from which the API is accessed is carried out using a token, which is generated by the bot provider. The client receives the token from the bot provider and inserts it in the settings of the connected bot channel in JivoChat. All requests from JivoChat to the bot provider and vice versa occur using this token, which is passed to the request URL. Format:
POST https://{bot_endpoint}/token
Content-Type: application/json
POST https://bot.jivosite.com/webhooks/{provider_id}/{token}
Content-Type: application/json
...
POST https://bot-provider-endpoint.com/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
POST https://bot.jivosite.com/webhooks/Ee0CRkyDAp/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
Event types#
Message type | Direction | Description |
---|---|---|
CLIENT_MESSAGE | JivoChat API → Bot-Provider | Event of a new client message to which the bot provider needs to provide response options |
BOT_MESSAGE | Bot-Provider → JivoChat API | Bot response to a client's message |
INVITE_AGENT | Bot-Provider → JivoChat API | Dialogue transfer to the agent, if the bot has no answer options |
AGENT_JOINED | JivoChat API → Bot-Provider | An agent connected to the dialogue at the initiative of the bot provider or a client |
AGENT_UNAVAILABLE | JivoChat API → Bot-Provider | Event informing that at the moment there are no available agents in the application to receive a chat |
CHAT_CLOSED | JivoChat API → Bot-ProvideR | Event triggered when the chat is closed |
---|
CLIENT_MESSAGE
Case: the bot operator is connected to the communication channel -> the client writes a message -> JivoChat proxies the message to the bot provider -> the message is processed and the response is returned depending on the scenario.
Event Parameters
Name | Type | Description |
---|---|---|
id | String | Unique event identifier, used for logging and debugging |
client_id | String | The identifier of the user who writes to one of the JivoChat client's channels. Unique within the customer account |
chat_id | String | Chat identifier, in which the user-agent dialogue takes place. Unique within the customer account |
message | Message | Customer message |
Example
{
event: "CLIENT_MESSAGE",
id: "123e4567-e89b-12d3-a456-426655440000",
client_id: "1234",
chat_id: "213123",
message: {
type: "TEXT",
text: "Hello! How much is the delivery?",
timestamp: 1583910736
}
}
BOT_MESSAGE
Case: the client writes a message -> JivoChat proxies the message to the bot provider -> the message is processed -> the bot responds with the prepared message -> message is sent to the client.
Event parameters
Name | Type | Description |
---|---|---|
id | String | Unique event identifier, used for logging and debugging |
chat_id | String | Chat identifier, in which the user-agent dialogue takes place. Unique within the customer account |
message | Message | Messages from the bot |
Example
{
event: "BOT_MESSAGE",
id: "123e4567-e89b-12d3-a456-426655440000",
message: {
type: "BUTTONS",
title: "Are you interested in delivery within the New York area?",
text: "Are you interested in delivery within the New York area? Yes / No"
timestamp: 1583910736,
buttons: [
{
text: "Yes",
}, {
text: "No"
}
]
}
}
INVITE_AGENT
Case: the client writes a message -> JivoChat proxies the message to the bot provider -> the message is processed -> the bot does not have a prepared answer -> dialogue is transferred to the agent.
Event parameters
Name | Type | Description |
---|---|---|
id | String | Unique event identifier, used for logging and debugging |
client_id | String | The identifier of the user who writes to one of the JivoChat client's channels. Unique within the customer account |
chat_id | String | Chat identifier, in which the user-agent dialogue takes place. Unique within the customer account |
Example
{
event: "INVITE_AGENT",
id: "123e4567-e89b-12d3-a456-426655440000",
client_id: "1234",
chat_id: "213123"
}
AGENT_JOINED
Case: the client writes a message -> JivoChat proxies the message to the bot provider -> the message is processed -> the bot does not have a prepared answer -> dialogue is transferred to the agent -> the agent joins the chat.
Event parameters
Name | Type | Description |
---|---|---|
id | String | Unique event identifier, used for logging and debugging |
client_id | String | The identifier of the user who writes to one of the JivoChat client's channels. Unique within the customer account |
chat_id | String | Chat identifier, in which the user-agent dialogue takes place. Unique within the customer account |
Example
{
event: "AGENT_JOINED",
id: "123e4567-e89b-12d3-a456-426655440000",
client_id: "1234",
chat_id: "213123"
}
AGENT_UNAVAILABLE
Case: the bot provider transfers the chat to the agent, but there are no available agents in the application, then according to the bot script, it sends a message asking the user to leave their contact details.
Event parameters
Name | Type | Description |
---|---|---|
id | String | Unique event identifier, used for logging and debugging |
chat_id | String | Chat identifier, in which the user-agent dialogue takes place. Unique within the customer account |
client_id | String | The identifier of the user who writes to one of the JivoChat client's channels. Unique within the customer account |
Example
{
event: "AGENT_UNAVAILABLE",
id: "123e4567-e89b-12d3-a456-426655440000",
chat_id: "213123",
client_id: "213123"
}
Message types#
Message type | Description |
---|---|
TEXT | Plain, text message |
MARKDOWN | Markdown-formatted text message |
BUTTONS | Answer options buttons |
TEXT
Message parameters
Name | Type | Description |
---|---|---|
text | String | Message text |
timestamp | String | Message creation timestamp, unix time |
Example
{
type: "TEXT",
text: "Hello! What is your weekend routine?",
timestamp: 1583910736
}
MARKDOWN
Message parameters
Name | Type | Description |
---|---|---|
content | String | The message is in Markdown format. In the first version: link, bold, italic |
text | String | Text feedback for communication channels that do not support this type of message, otherwise the message will not be sent to the client |
timestamp | String | Message creation timestamp, unix time |
Example
{
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
}
BUTTONS
Message parameters
Name | Type | Description |
---|---|---|
buttons | Array | A set of buttons with prepared answers. Maximum of 3 buttons |
title | String | Text title for buttons |
text | String | Text feedback for communication channels that do not support this type of message, otherwise the message will not be sent to the client |
button.text | String | Text of the prepared answer |
timestamp | String | Message creation timestamp, unix time |
Example
{
type: "BUTTONS",
title: "Could you please specify the desired delivery service?"
text: "Could you please specify the desired delivery service? PEC and Boxberry are available",
buttons: [
{
text: "PEC"
},
{
text: "Boxberry"
}
],
timestamp: 1583910736
}