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

All events from JivoChat 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	JivoChat API → Bot-Provider	New client message event, that requires response options
BOT_MESSAGE	Bot-Provider → JivoChat API	Bot's response to a client message
INVITE_AGENT	Bot-Provider → JivoChat API	Chat transfer from a bot to an agent
AGENT_UNAVAILABLE	JivoChat API → Bot-Provider	Event, informing that no agents are available to accept the chat at the moment
CHAT_CLOSED	JivoChat 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	JivoChat 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 JivoChat 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

4. VIDEO, PHOTO#

The message format for these types is the same, the only difference is the type.

A file is transferred by passing a link to it.

Example


  "message": {
    type: "VIDEO",
    file: "https://example.com/video.mp4",
    file_name: "video.mp4"
    file_size: 1583910736,
    thumb: "https://example.com/thumb.jpg"
  }


  "message": {
    type: "PHOTO",
    file: "https://example.com/image.jpg",
    file_name: "image.jpg",
    text: 'Высылаю вам изображение',
    file_size: 1583910736,
    thumb: "https://example.com/thumb.jpg"
  }

Name	Type	Description
file	string	URL to download the file (mandatory parameter)
file_name	string	File name
file_size	int	File size, in bytes
text	string	Text attached to the message
thumb	string	URL of the preview image

5. AUDIO, VOICE, DOCUMENT#

These are the same types as PHOTO and VIDEO, just without the preview image.

A file is transferred by passing a link to it.

Example


  "message": {
    type: "AUDIO",
    file: "https://example.com/audio.mp3",
    file_name: "audio.mp3",
    file_size: 2048, 
  }


  "message": {
    type: "VOICE",
    file: "https://example.com/voice.mp3",
    file_name: "voice.mp3",
    text: 'Прикрепленный текст',
    file_size: 2048,
  }


  "message": {
    type: "DOCUMENT",
    file: "https://example.com/document.pdf",
    file_name: "document.pdf",
    file_size: 2048,
  }

Name	Type	Description
file	string	URL to download the file (mandatory parameter)
file_name	string	File name
file_size	int	File size, in bytes
text	string	Text attached to the message

6. LOCATION#

Example


  "message": {
    type: "LOCATION",
    latitude: 53.3416484,
    longitude: -6.2868531
  }

Name	Type	Description
latitude	float	Latitude value (mandatory parameter)))
longitude	float	Longitude value (mandatory parameter)

INVITE_AGENT#

The event is sent from bot-provider to JivoChat 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 JivoChat 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`

INIT_RATE#

The bot provider requests the display of a form to assess the quality of service in the chat.

Note that the score obtained by calling this method is not saved in JivoChat, but is transferred to the bot provider for storage and use.


{
    "event": "INIT_RATE",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "client_id": "2",
    "chat_id": "4"
}

Event Parameters

Name	Type	Description
id	string	Unique event identifier, used for logging and debugging purposes
client_id	string	Identifier of the customer who writes to one of Jivo's channels Jivo `unique within the account`
chat_id	string	Identifier of the chat room where the dialog with the client will be entered `unique within the account`

CLIENT_RATED#

The client left an estimate in the form called by the INIT_RATE method.

Note that the score obtained by calling this method is not saved in Jivo, but is transferred to the bot provider for storage and use.


{
  "id": "43d7b5de-d93c-11ed-ba4b-457f317d3806",
  "site_id": "540670",
  "client_id": "47454",
  "chat_id": "4",
  "agents_online": true,
  "sender": {
    "id": 47454,
    "name": "client_name"
  },
  "rate": {
    "rating": "good",
    "comment": "Все было супер!",
    "timestamp": 1681308837
  },
  "channel": {
    "id": "1hjSGtiQ6e",
    "type": "widget"
  },
  "event": "CLIENT_RATED",
  "options": null

}

Name	Тype	Description
id	string	Unique event identifier, used for logging and debugging purposes
client_id	string	Identifier of the customer who writes to one of Jivo's channels `unique within the account`
chat_id	string	Identifier of the chat room in which the dialog with the client will be entered`unique within the account`
agents_online	boolean	Agent status indicator (online or offline)
sender	object	Client information: id - client_id (int), name - client name (string)
channel	object	Information about the channel in which the message arrived: id - unique channel identifier (string), type - channel type (string)
rate	object	rating - rating given by the client with possible values: 'bad', 'badnormal', 'normal', 'goodnormal', 'good' (string); comment - comment to the rating (string)

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.