Bot API

Using Bot API you can connect a chatbot to your account to process incoming chats. The events exchange works via the webhooks mechanism. The initiator of the exchange is Jivo.

All events from Jivo to the bot provider and back are sent as HTTPS requests using the POST method in application/json format. The request timeout is 3 seconds, with 2 retries until a regular successful response is received. If not, the chat is transferred to the agent. This gives bot-providers 9 seconds to update the software on the server which is enough in most cases.

Event types

Message type	Direction	Description
CLIENT_MESSAGE	Jivo API → Bot-Provider	New client message event, that requires response options
BOT_MESSAGE	Bot-Provider → Jivo API	Bot's response to a client message
INVITE_AGENT	Bot-Provider → Jivo API	Chat transfer from a bot to an agent
AGENT_UNAVAILABLE	Jivo API → Bot-Provider	Event, informing that no agents are available to accept the chat at the moment
CHAT_CLOSED	Jivo API → Bot-Provider	Chat closing event

CLIENT_MESSAGE

This event is intended to transfer a client's message to the bot provider. The request with the message is processed, and the bot's response is sent into the chat.

Example

{
  "id": "9661ab9c-48b0-11ed-a3d6-859398ff9bd9",
  "site_id": "123456",
  "client_id": "1233",
  "chat_id": "2037",
  "agents_online": true,
  "sender": {
    "id": 1233,
    "name": "John Smith",
    "url": "https://test.com",
    "has_contacts": true
  },
  "message": {
    "type": "TEXT",
    "text": "Can you help me?",
    "timestamp": 1665415879
  },
  "channel": {
    "id": "12345678",
    "type": "widget"
  },
  "event": "CLIENT_MESSAGE"
}

Event parameters

Name	Type	Description
id	string	Unique event ID used for debugging
site_id	string	Jivo account ID, to which a request belongs
client_id	string	ID of a client, who writes to one of the JivoChat channels `Unique within the account`
chat_id	string	ID of a chat, where conversation takes place `Unique within the account`
agents_online	boolean	Agent status identifier (if the value is true, agents are online; false - agents are offline)
sender	object	Information about the client
message	object	Information about the message that was sent
channel	object	Information about the channel where the message was sent
event	string	Event type

sender

Наименование	Тип	Описание
id	int	ID of a client (similar to client_id)
user_token `optional`	string	Client's ID sent using API-method
name `optional`	string	Client's name
url	string	URL of a page, from which a client sent a message
has_contacts	boolean	Informs, whether a client has contacts details or not

message

Name	Type	Description
type	string	Message type
text	string	Message text
timestamp	int	Time logging parameter

channel

Name	Type	Description
id	string	ID of the channel where the message was sent
type	string	Channel type

BOT_MESSAGE

This request type is used to transmit a bot response to a chat with a client. It is sent from bot provider to Jivo endpoint.

Example

{   
  "id": "093e9c6a-48b6-11ed-907d-7d426317dad5",
  "client_id": "1235",
  "chat_id": "2041",
  "message": {
    "type": "BUTTONS",
      "title": "Would you like to make an order?",
      "text": "Would you like to make an order? Yes / No",
      "timestamp": 1583910736,
      "force_reply": true,
      "buttons": [
        {
          "text": "Yes",
          "id": 1
        }, {
          "text": "No",
          "id": 2
        }
      ]
  },
  "event": "BOT_MESSAGE",
}

Event parameters

Name	Type	Description
id	string	Unique event ID used for debugging
client_id	string	ID of a client, who writes to one of the JivoChat channels `Unique within the account`
chat_id	string	ID of a chat where conversation takes place `Unique within the account`
message	object	Bot message

Bot messages types

1. TEXT

Simple text message

Example

 {
   "message": {
     "type": "TEXT",
     "text": "Hello! How can I help you?",
     "timestamp": 1653127681833
  },
 }

Name	Type	Description
text	string	Message text
timestamp	int	Time logging parameter, unix time

2. MARKDOWN

Text message in Markdown format

Example

 {
   "message": {
     "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
  },
 }

Name	Type	Description
сontent	string	Message in Markdown format (the following styles are supported: link, bold, italic)
text	string	Text fallback for channels that don't support markdown format. If not specified, a message won't be sent to a client
timestamp	int	Time logging parameter, unix time

3. BUTTONS

Example

  "message": {
    "type": "BUTTONS",
    "title": "Would you like to make an order?",
    "text": "Would you like to make an order? Yes / No",
    "force_reply": true,
    "buttons": [
      {
        "text": "Yes",
        "id": 1
      }, {
        "text": "No",
        "id": 2
      }
    ],
    "timestamp": 1583910736,
  }

Name	Type	Description
title	string	Text title for buttons
text	string	Text fallback for channels that don't support markdown format. If not specified, a message won't be sent to a client
force_reply `optional`	boolean	If there is true value, the message input field is blocked, so a client chooses one of the suggested buttons
buttons	array	Set of buttons with canned replies
buttons.text	string	Canned reply text
button.id	string	ID of a button, sent in chat

INVITE_AGENT

The event is sent from bot-provider to Jivo if it is required to transfer a chat to an agent.

Example

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

Event parameters

Name	Type	Description
id	string	Unique event ID used for debugging
client_id	string	ID of a client, who writes to one of the JivoChat channels `Unique within the account`
chat_id	string	ID of a chat where conversation takes place `Unique within the client's account`

AGENT_UNAVAILABLE

The following event is sent from Jivo to bot-provider in case if bot transfers a chat to agents and there are no agents online ready to accept a chat. After processing this request bot can continue communicating with a client, for example, it can request contacts from a user.

Example

{
  "id": "f061d944-48bc-11ed-a11a-9b4e3e49df1b",
  "chat_id": "2043",
  "client_id": "1236",
  "event": "AGENT_UNAVAILABLE"
}

Event parameters

Name	Type	Description
id	string	Unique event ID used for debugging
client_id	string	ID of a client who writes to one of the channels `Unique within the client's account`
chat_id	string	ID of a chat where conversation takes place `Unique within the account`

CHAT_CLOSED

This type of request is sent when an agent accepts a chat, or it is automatically closed by timeout. If bot provider receives this event, the bot will no longer be able to send messages to this chat.

Example

{
  "id": "f9e59d98-48bc-11ed-896a-47ed16cbbd46",
  "chat_id": "2043",
  "client_id": "1236",
  "event": "CHAT_CLOSED"
}

Event parameters

Name	Type	Description
id	string	Unique event ID used for debugging
client_id	string	ID of a client who writes to one of the channels `Unique within the client's account`
chat_id	string	ID of a chat where conversation takes place `Unique within the account`

The integration workflow and description of possible errors can be found in our help base article. In case of any questions please feel free to contact us by email info@jivochat.com or in chat.