Документация

Bot API

Используя Бот API, вы можете подключить чат-бота в свой аккаунт для обработки входящих диалогов. Обмен событиями происходит посредством механизма webhooks. Инициатором обмена является Jivo - бот-провайдеру отправляется запрос с сообщением клиента.

Все события от Jivo к бот-провайдеру и обратно отправляются в виде HTTPS-запросов, методом POST в формате application/json. Timeout запроса составляет 3 секунды, количество повторных попыток равно 2, до тех пор, пока не будет получен штатный успешный ответ, иначе клиент переводится на оператора. Это дает 9 секунд на обновление ПО на сервере, чего хватает в большинстве случаев.

Коды ответа

Ниже в таблице приведен список возможных кодов ответа от Jivo и бот-провайдера:

Коды ответа Описание
200 OK Успешный, штатный ответ.
400 Bad Request Неверный формат запроса. Необходимо проверить поля запроса на соответствие формату API
401 Unauthorized Ошибка авторизации
403 Forbidden Доступ запрещен
404 Not Found Неправильно сформирован endpoint
405 Method Not Allowed Данный метод или событие не поддерживается
429 Too Many Request Превышено кол-во запросов в единицу времени
500 Internal Server Error Ошибка обработки запроса
502 Bad Gateway Сервер перегружен
503 Service Unavailable Сервер недоступен
504 Gateway Timeout Не удалось спроксировать запрос

В случае возникновения нештатной ситуации, в тело ответа рекомендуется передавать информацию об ошибке в следующем формате:

{
  "error" :
    {
      "code": "<код ошибки>",
      "message": "<human-readable сообщение ошибки>"
    }
}

Коды ошибок#

Код Описание
invalid_client Ошибка аутентификации клиента по токену. Возвращается вместе с HTTP кодом 401 Unauthorized.
unauthorized_client Ошибка авторизации по средствам заголовка Authorization
invalid_request В запросе отсутствует обязательный параметр, либо используется неподдерживаемое значение параметра, содержится дубликат параметра, включено несколько наборов учетных данных, либо другие ошибки запроса.

Аутентификация#

Аутентификация клиента бот-провайдера, от которого идет обращение в API, осуществляется c помощью токена, который формируется на стороне бот-провайдера.

Вам нужно получить токен у бот-провайдера и указать его в настройках подключенного бот-оператора в Jivo. Все обращения от Jivo к бот-провайдеру и обратно происходят с использованием данного токена, который передается в URL запроса.

Токен бот-провайдера должен быть уникальным. Если использовать одинаковый токен для нескольких ботов, они не смогут быть аутентифицированы и не будут работать.

Пример:

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

Типы событий#

Тип сообщенийНаправлениеОписание
CLIENT_MESSAGEJivo API → Bot-ProviderСобытие о новом сообщении клиента, на которое бот-провайдеру надо предоставить варианты ответа
BOT_MESSAGEBot-Provider → Jivo APIОтвет бота на сообщение клиента
INVITE_AGENTBot-Provider → Jivo APIПеревод диалога на оператора
AGENT_UNAVAILABLEJivo API → Bot-ProviderСобытие о том, что в данный момент нет ни одного доступного оператора в сети, который мог бы принять чат
CHAT_CLOSEDJivo API → Bot-ProviderСобытие о закрытии чата
INIT_RATEBot-Provider → Jivo APIСобытие вызывает в виджете форму-оценки диалога, если она настроена
CLIENT_RATEDJivo API → Bot-ProviderСобытие об оценке в виджете с результатами оценки пользователя

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

Параметры события

НаименованиеТипОписание
idstringУникальный идентификатор события, используется для логирования и дебага
site_idstringИдентификатор аккаунта Jivo, с которого пришёл запрос
client_idstringИдентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта
chat_idstringИдентификатор чата, в котором ведется диалог Уникальный в рамках аккаунта
agents_onlinebooleanИндикатор статуса операторов: онлайн или офлайн
senderobjectИнформация о клиенте
messageobjectДанные об отправленном сообщении
channelobjectИнформация о канале, в котором было отправлено сообщение
eventstringТип события

sender

НаименованиеТипОписание
idintИдентификатор клиента (аналогично client_id)
user_token необязательныйstringИдентификатор пользователя, переданный через API-метод
name необязательныйstringИмя клиента
urlstringАдрес страницы, с которой написал клиент
has_contactsbooleanИнформирует о том, указаны ли у пользователя контактные данные

message

НаименованиеТипОписание
typestringТип сообщения
textstringТекст сообщения
timestampintМетка времени

channel

НаименованиеТипОписание
idstringИдентификатор канала, с которого было отправлено сообщение клиента
typestringТип канала

Передача сообщений типов VIDEO, PHOTO, AUDIO, VOICE, DOCUMENT недоступна по умолчанию, и включается по запросу для каждого бот-провайдера. Если вы поддерживаете методы передачи файлов и хотите реализовать ее, обратитесь в поддержку Jivo.

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

Параметры события

НаименованиеТипОписание
idstringУникальный идентификатор события, используется для логирования и дебага
client_idstringИдентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта
chat_idstringИдентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта
messageobjectСообщение бота

Типы сообщений бота#

ТипОписание
TEXTТекстовое сообщение
MARKDOWNТекстовое сообщение в формате Markdown
BUTTONSВарианты ответа в виде кнопок
VIDEOВидео
PHOTOИзображение
AUDIOАудио
VOICEГолосовое сообщение
DOCUMENTДокумент
LOCATIONМестоположение
1. TEXT#
  • Пример
{ "message": { "type": "TEXT", "text": "Здравствуйте! Чем могу вам помочь? ", "timestamp": 1653127681833 }, }
НаименованиеТипОписание
textstringТекст сообщения
timestampintВременная метка создания сообщения, unix time
2. MARKDOWN#
  • Пример
{ "message": { "type": "MARKDOWN", "content": "Чтобы отключить **PUSH-уведомления**, выполните действия, описанные в [инструкции](https://site.com/page_url)", "text": "Чтобы отключить PUSH-уведомления, выполните действия, описанные в инструкции https://site.com/page_url", "timestamp": 1583910736 }, }
НаименованиеТипОписание
сontentstringСообщение в формате Markdown (поддерживается link, bold, italic, strikethrough и image (inline) )
textstringТекстовый fallback для каналов связи, которые не поддерживают данный тип сообщений, иначе сообщение не будет отправлено клиенту
timestampintВременная метка создания сообщения, unix time
3. BUTTONS#
  • Пример
"message": { "type": "BUTTONS", "title": "Вас интересует доставка в пределах МКАД?", "text": "Вас интересует доставка в пределах МКАД? Выберите да или нет", "force_reply": true, "buttons": [ { "text": "Да", "id": 1 }, { "text": "Нет", "id": 2 } ], "timestamp": 1583910736, }
НаименованиеТипОписание
titlestringТекстовый заголовок для кнопок
textstringТекстовый fallback для каналов связи, которые не поддерживают данный тип сообщений, иначе сообщение не будет отправлено клиенту
force_reply НеобязательныйbooleanЕсли приходит true, поле ввода сообщения в виджете блокируется, чтобы пользователь выбрал одну из отправленных кнопок
buttonsarrayНабор кнопок с заготовленными ответами
buttons.textstringТекст заготовленного ответа
button.idstringИдентификатор отправленной кнопки
4. VIDEO, PHOTO#

Формат сообщения для этих типов одинаковый, отличие только в type.

Файл передается посредством передачи ссылки на него.

  • Пример
"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" }
НаименованиеТипОписание
filestringURL для скачивания файла (обязательный параметр)
file_namestringНаименование файла
file_sizeintРазмер файла, исчисляемое в байтах
textstringТекст прикрепленный к сообщению
thumbstringURL изображения для предпросмотра
5. AUDIO, VOICE, DOCUMENT#

Это такие же типы, как PHOTO и VIDEO, только без изображения для предпросмотра.

Файл передается посредством передачи ссылки на него.

  • Пример
"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, }
НаименованиеТипОписание
filestringURL для скачивания файла (обязательный параметр)
file_namestringНаименование файла
file_sizeintРазмер файла, исчисляемое в байтах
textstringТекст прикрепленный к сообщению
6. LOCATION#
  • Пример
"message": { "type": "LOCATION", "latitude": 53.3416484, "longitude": -6.2868531 }
НаименованиеТипОписание
latitudefloatЗначение широты (обязательный параметр))
longitudefloatЗначение долготы (обязательный параметр)

INVITE_AGENT#

Отправляется от бот-провайдера в Jivo в случае, если необходимо перевести диалог на оператора.

Пример

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

Параметры события

НаименованиеТипОписание
idstringУникальный идентификатор события, используется для логирования и дебага
client_idstringИдентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта
chat_idstringИдентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта

AGENT_UNAVAILABLE#

Бот переводит чат на оператора. Если операторов в сети нет, то бот-провайдеру отправляется соответствующее событие. В этом случае бот может продолжить общение с клиентом - например, запросить контакты.

Пример

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

Параметры события

НаименованиеТипОписание
idstringУникальный идентификатор события, используется для логирования и дебага
client_idstringИдентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта
chat_idstringИдентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта

CHAT_CLOSED#

Отправляется, если чат был принят оператором или автоматически закрылся по таймауту. Если бот-провайдеру поступило это событие, бот больше не сможет отправлять сообщения в этот чат.

Пример

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

Параметры события

НаименованиеТипОписание
idstringУникальный идентификатор события, используется для логирования и дебага
client_idstringИдентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта
chat_idstringИдентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта

INIT_RATE#

Бот-провайдер запрашивает показ формы для оценки качества обслуживания в диалоге.

Обратите внимание, что оценка, полученная вызовом этого метода, не сохраняется в Jivo, а передается на хранение и использование бот-провайдеру.

Пример

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

Параметры события

НаименованиеТипОписание
idstringУникальный идентификатор события, используется для логирования и дебага
client_idstringИдентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта
chat_idstringИдентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта

CLIENT_RATED#

Клиент оставил оценку в форме, вызванной методом INIT_RATE.

Обратите внимание, что оценка, полученная вызовом этого метода, не сохраняется в Jivo, а передается на хранение и использование бот-провайдеру.

Пример

{ "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 }
НаименованиеТипОписание
idstringУникальный идентификатор события, используется для логирования и дебага
client_idstringИдентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта
chat_idstringИдентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта
agents_onlinebooleanИндикатор статуса операторов (онлайн или офлайн)
senderobjectИнформация о клиенте: id - client_id (int), name - имя клиента (string)
channelobjectИнформация о канале, в котором пришло сообщение: id - уникальный идентификатор канала (string), type - тип канала (string)
rateobjectrating - оценка, которую выставил клиент с возможными значениями: 'bad', 'badnormal', 'normal', 'goodnormal', 'good' (string); comment - комментарий к оценке (string)

Схема интеграции бота и описание возможных ошибок доступны в статье в нашей базе знаний. Если у вас возникли какие-либо вопросы, вы можете прислать их в чате c нами или на почту info@jivo.ru.