Bot API

Included for free in plans
VIPPRO

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 codesDescription
200 OKSuccessful, regular response
400 Bad RequestInvalid request format. You must check the request fields for compliance with the API format
401 UnauthorizedAuthorization error
403 ForbiddenAccess denied
404 Not FoundIncorrectly formed endpoint
405 Method Not AllowedThis method or event is not supported
429 Too Many RequestExceeded requests per unit time
500 Internal Server ErrorRequest processing error
502 Bad GatewayServer is overloaded
503 Service UnavailableServer is not available
504 Gateway TimeoutFailed 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

CodeDescription
invalid_clientToken client authentication error. Returned with HTTP code 401 Unauthorized
unauthorized_clientAuthorization failed by header Authorization
invalid_requestThe 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 typeDirectionDescription
CLIENT_MESSAGEJivoChat API → Bot-ProviderEvent of a new client message to which the bot provider needs to provide response options
BOT_MESSAGEBot-Provider → JivoChat APIBot response to a client's message
INVITE_AGENTBot-Provider → JivoChat APIDialogue transfer to the agent, if the bot has no answer options
AGENT_JOINEDJivoChat API → Bot-ProviderAn agent connected to the dialogue at the initiative of the bot provider or a client
AGENT_UNAVAILABLEJivoChat API → Bot-ProviderEvent informing that at the moment there are no available agents in the application to receive a chat
CHAT_CLOSEDJivoChat API → Bot-ProvideREvent 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

NameTypeDescription
idStringUnique event identifier, used for logging and debugging
client_idStringThe identifier of the user who writes to one of the JivoChat client's channels. Unique within the customer account
chat_idStringChat identifier, in which the user-agent dialogue takes place. Unique within the customer account
messageMessageCustomer 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

NameTypeDescription
idStringUnique event identifier, used for logging and debugging
chat_idStringChat identifier, in which the user-agent dialogue takes place. Unique within the customer account
messageMessageMessages 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

NameTypeDescription
idStringUnique event identifier, used for logging and debugging
client_idStringThe identifier of the user who writes to one of the JivoChat client's channels. Unique within the customer account
chat_idStringChat 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

NameTypeDescription
idStringUnique event identifier, used for logging and debugging
client_idStringThe identifier of the user who writes to one of the JivoChat client's channels. Unique within the customer account
chat_idStringChat 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

NameTypeDescription
idStringUnique event identifier, used for logging and debugging
chat_idStringChat identifier, in which the user-agent dialogue takes place. Unique within the customer account
client_idStringThe 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 typeDescription
TEXTPlain, text message
MARKDOWNMarkdown-formatted text message
BUTTONSAnswer options buttons

TEXT

Message parameters

NameTypeDescription
textStringMessage text
timestampStringMessage creation timestamp, unix time

Example

{
  type: "TEXT",
  text: "Hello! What is your weekend routine?",
  timestamp: 1583910736
}

MARKDOWN

Message parameters

NameTypeDescription
contentStringThe message is in Markdown format. In the first version: link, bold, italic
textStringText feedback for communication channels that do not support this type of message, otherwise the message will not be sent to the client
timestampStringMessage 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

NameTypeDescription
buttonsArrayA set of buttons with prepared answers. Maximum of 3 buttons
titleStringText title for buttons
textStringText feedback for communication channels that do not support this type of message, otherwise the message will not be sent to the client
button.textStringText of the prepared answer
timestampStringMessage 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
}
Have questions?
Ask in the live chat, we are ready to help around the clock