Bot API

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.

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

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

Event types

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

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

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

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

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

Example

{
  event: "AGENT_UNAVAILABLE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  chat_id: "213123",
  client_id: "213123"
}

Message types

TEXT

Message parameters

Example

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

MARKDOWN

Message parameters

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

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
}