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
}