Bot API
Используя Бот API, вы можете подключить чат-бота в свой аккаунт для обработки входящих диалогов. Обмен событиями происходит посредством механизма webhooks. Инициатором обмена является Jivo - бот-провайдеру отправляется запрос с сообщением клиента.
Все события от Jivo к бот-провайдеру и обратно отправляются в виде HTTPS-запросов, методом POST в формате application/json
. Timeout запроса составляет 3 секунды, количество повторных попыток равно 2, до тех пор, пока не будет получен штатный успешный ответ, иначе клиент переводится на оператора. Это дает 9 секунд на обновление ПО на сервере, чего хватает в большинстве случаев.
Типы событий
Тип сообщений | Направление | Описание |
---|---|---|
CLIENT_MESSAGE | Jivo API → Bot-Provider | Событие о новом сообщение клиента, на которое бот-провайдеру надо предоставить варианты ответа |
BOT_MESSAGE | Bot-Provider → Jivo API | Ответ бота на сообщение клиента |
INVITE_AGENT | Bot-Provider → Jivo API | Перевод диалога на оператора |
AGENT_UNAVAILABLE | Jivo API → Bot-Provider | Событие о том, что в данный момент нет ни одного доступного оператора в сети, которые могли бы принять чат |
CHAT_CLOSED | Jivo API → Bot-Provider | Событие о закрытии чата |
CLIENT_INFO | Bot-Provider → Jivo API | Событие с контактной информацией о клиенте |
CLIENT_MESSAGE
Используется для передачи сообщения клиента бот-провайдеру. Запрос с сообщением обрабатывается, и в диалог возвращается ответ бота.
Пример
{ "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": "Вы можете мне помочь?", "timestamp": 1665415879 }, "channel": { "id": "12345678", "type": "widget" }, "event": "CLIENT_MESSAGE" }
Параметры события
Наименование | Тип | Описание |
---|---|---|
id | string | Уникальный идентификатор события, используется для логирования и дебага |
site_id | string | Идентификатор аккаунта Jivo, с которого пришёл запрос |
client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
chat_id | string | Идентификатор чата, в котором ведется диалог Уникальный в рамках аккаунта |
agents_online | boolean | Идентификатор статуса операторов (онлайн или офлайн) |
sender | object | Информация о клиенте |
message | object | Данные об отправленном сообщении |
channel | object | Информация о канале, в котором было отправлено сообщение |
event | string | Тип события |
sender
Наименование | Тип | Описание |
---|---|---|
id | int | Идентификатор клиента (аналогично client_id) |
user_token необязательный | string | Идентификатор пользователя, переданный через API-метод |
name необязательный | string | Имя клиента |
url | string | Адрес страницы, с которой написал клиент |
has_contacts | boolean | Информирует о том, указаны ли у пользователя контактные данные |
message
Наименование | Тип | Описание |
---|---|---|
type | string | Тип сообщения |
text | string | Текст сообщения |
timestamp | int | Метка времени |
channel
Наименование | Тип | Описание |
---|---|---|
id | string | Идентификатор канала, с которого было отправлено сообщение клиента |
type | string | Тип канала |
BOT_MESSAGE
Используется для проксирования ответа бота в диалог клиенту. Отправляется от бот-провайдера в Jivo.
Пример
{ "id": "093e9c6a-48b6-11ed-907d-7d426317dad5", "client_id": "1235", "chat_id": "2041", "message": { "type": "BUTTONS", "title": "Вас интересует доставка в пределах МКАД?", "text": "Вас интересует доставка в пределах МКАД? Да / Нет", "timestamp": 1583910736, "force_reply": true, "buttons": [ { "text": "Да", "id": 1 }, { "text": "Нет", "id": 2 } ] }, "event": "BOT_MESSAGE", }
Параметры события
Наименование | Тип | Описание |
---|---|---|
id | string | Уникальный идентификатор события, используется для логирования и дебага |
client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
chat_id | string | Идентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта |
message | object | Сообщение бота |
Типы сообщений бота
Тип | Описание |
---|---|
TEXT | Текстовое сообщение |
MARKDOWN | Текстовое сообщение в формате Markdown |
BUTTONS | Варианты ответа в виде кнопок |
1. TEXT
- Пример
{ "message": { "type": "TEXT", "text": "Здравствуйте! Чем могу вам помочь? ", "timestamp": 1653127681833 }, }
Наименование | Тип | Описание |
---|---|---|
text | string | Текст сообщения |
timestamp | int | Временная метка создания сообщения, unix time |
2. MARKDOWN
- Пример
{ "message": { "type": "MARKDOWN", "content": "Чтобы отключить **PUSH-уведомления**, выполните действия, описанные в [инструкции](https://site.com/page_url)", "text": "Чтобы отключить PUSH-уведомления, выполните действия, описанные в инструкции https://site.com/page_url", "timestamp": 1583910736 }, }
Наименование | Тип | Описание |
---|---|---|
сontent | string | Сообщение в формате Markdown (поддерживается link, bold, italic) |
text | string | Текстовый fallback для каналов связи, которые не поддерживают данный тип сообщений, иначе сообщение не будет отправлено клиенту |
timestamp | int | Временная метка создания сообщения, unix time |
3. BUTTONS
- Пример
"message": { "type": "BUTTONS", "title": "Вас интересует доставка в пределах МКАД?", "text": "Вас интересует доставка в пределах МКАД? Выберите да или нет", "force_reply": true, "buttons": [ { "text": "Да", "id": 1 }, { "text": "Нет", "id": 2 } ], "timestamp": 1583910736, }
Наименование | Тип | Описание |
---|---|---|
title | string | Текстовый заголовок для кнопок |
text | string | Текстовый fallback для каналов связи, которые не поддерживают данный тип сообщений, иначе сообщение не будет отправлено клиенту |
force_reply Необязательный | boolean | Если приходит true, поле ввода сообщения в виджете блокируется, чтобы пользователь выбрал одну из отправленных кнопок |
buttons | array | Набор кнопок с заготовленными ответами |
buttons.text | string | Текст заготовленного ответа |
button.id | string | Идентификатор отправленной кнопки |
INVITE_AGENT
Отправляется от бот-провайдера в Jivo в случае, если необходимо перевести диалог на оператора.
Пример
{ "id": "123e4567-e89b-12d3-a456-426655440000", "client_id": "1234", "chat_id": "213123", "event": "INVITE_AGENT" }
Параметры события
Наименование | Тип | Описание |
---|---|---|
id | string | Уникальный идентификатор события, используется для логирования и дебага |
client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
chat_id | string | Идентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта |
AGENT_UNAVAILABLE
Бот переводит чат на оператора. Если операторов в сети нет, то бот-провайдеру отправляется соответствующее событие. В этом случае бот может продолжить общение с клиентом - например, запросить контакты.
Пример
{ "id": "f061d944-48bc-11ed-a11a-9b4e3e49df1b", "chat_id": "2043", "client_id": "1236", "event": "AGENT_UNAVAILABLE" }
Параметры события
Наименование | Тип | Описание |
---|---|---|
id | string | Уникальный идентификатор события, используется для логирования и дебага |
client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
chat_id | string | Идентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта |
CHAT_CLOSED
Отправляется, если чат был принят оператором или автоматически закрылся по таймауту. Если бот-провайдеру поступило это событие, бот больше не сможет отправлять сообщения в этот чат.
Пример
{ "id": "f9e59d98-48bc-11ed-896a-47ed16cbbd46", "chat_id": "2043", "client_id": "1236", "event": "CHAT_CLOSED" }
Параметры события
Наименование | Тип | Описание |
---|---|---|
id | string | Уникальный идентификатор события, используется для логирования и дебага |
client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
chat_id | string | Идентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта |
CLIENT_INFO
Используется для передачи контактных данных клиента от бот-провайдера в Jivo в ответ на сообщение клиента. Контакты отобразятся в приложении Jivo в диалоге в информационной панели справа.
Пример
{ "id": "996344da-d8f4-11ec-9aaf-c5bde7170335", "client_id": "1237", "client": { "email": "example@post.ru", "phone": "89754154877", "name": "Иван" }, "event": "CLIENT_INFO" }
Параметры события
Наименование | Тип | Описание |
---|---|---|
id | string | Уникальный идентификатор события, используется для логирования и дебага |
client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
client | object | Контактная информация о клиенте (email, phone, name) |
Схема интеграции бота и описание возможных ошибок доступны в статье в нашей базе знаний. Если у вас возникли какие-либо вопросы, вы можете прислать их в чате c нами или на почту info@jivo.ru.