Bot API

Choose another article

Our Bot API allows you to connect bot platforms to any conversations in Jivo: 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 Jivo. This happens when there’s an incoming message from a client. Events are exchanged with bot providers using the webhooks mechanism. All events from Jivo are sent to the endpoint of the provider and, in response, the provider sends events to Jivo’s endpoint.

All events from Jivo 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. Jivo’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 Jivo 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 Jivo. All requests from Jivo 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

Authorization

On top of authentication, you can optionally use an additional security measure in the form of an authorization token, which is issued by the bot provider to Jivo and has a limited lifetime. To do this, Jivo first receives a temporary access token in exchange for a secret key and client_id, after which it is transmitted each time the bot provider is accessed and back in the Authorization header. Example:

POST https://bot-provider-endpoint.com/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
Authorization: 92753d11-4aef-459a-8d45-1c1faabb6e36

...

POST https://bot.jivosite.com/providers/Ee0CRkyDAp/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
Authorization: 92753d11-4aef-459a-8d45-1c1faabb6e36

Event types

Message type Direction Description
CLIENT_MESSAGE Jivo API → Bot-Provider Event of a new client message to which the bot provider needs to provide response options
BOT_MESSAGE Bot-Provider → Jivo API Bot response to a client’s message
INVITE_AGENT Bot-Provider → Jivo API Dialogue transfer to the agent, if the bot has no answer options
AGENT_JOINED Jivo API → Bot-Provider An agent connected to the dialogue at the initiative of the bot provider or a client
AGENT_UNAVAILABLE Jivo API → Bot-Provider Event informing that at the moment there are no available agents in the application to receive a chat

CLIENT_MESSAGE

Case: the bot operator is connected to the communication channel -> the client writes a message -> Jivo 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 Jivo 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 -> Jivo 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",
          id: 1,
        }, {
          text: "No",
          id: 2
        }
      ]
  }
}

INVITE_AGENT

Case: the client writes a message -> Jivo 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 Jivo 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 -> Jivo 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 Jivo 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 Jivo 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
button_id String (optional) ID of the button clicked by the user
timestamp String Message creation timestamp, unix time

Example

{
  type: "TEXT",
  text: "Hello! What is your weekend routine?",
  button_id: "123",
  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
button_id String optional ID of the button clicked by the user
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<button> 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
button.id String ID 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",
      id: "1"
    },
    {
      text: "Boxberry",
      id:"2"
    }
  ],
  timestamp: 1583910736
}

Do you still have any questions? Our support team will be more than happy to help you 24x7 in the chat on our site.