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_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 | Событие о закрытии чата |
| INIT_RATE | Bot-Provider → Jivo API | Событие вызывает в виджете форму-оценки диалога, если она настроена |
| CLIENT_RATED | Jivo 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" }
Параметры события
| Наименование | Тип | Описание |
|---|---|---|
| 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 | Тип канала |
Передача сообщений типов 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" }
Параметры события
| Наименование | Тип | Описание |
|---|---|---|
| id | string | Уникальный идентификатор события, используется для логирования и дебага |
| client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
| chat_id | string | Идентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта |
| message | object | Сообщение бота |
Типы сообщений бота#
| Тип | Описание |
|---|---|
| TEXT | Текстовое сообщение |
| MARKDOWN | Текстовое сообщение в формате Markdown |
| BUTTONS | Варианты ответа в виде кнопок |
| VIDEO | Видео |
| PHOTO | Изображение |
| AUDIO | Аудио |
| VOICE | Голосовое сообщение |
| DOCUMENT | Документ |
| LOCATION | Местоположение |
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 | Идентификатор отправленной кнопки |
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" }
| Наименование | Тип | Описание |
|---|---|---|
| file | string | URL для скачивания файла (обязательный параметр) |
| file_name | string | Наименование файла |
| file_size | int | Размер файла, исчисляемое в байтах |
| text | string | Текст прикрепленный к сообщению |
| thumb | string | URL изображения для предпросмотра |
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, }
| Наименование | Тип | Описание |
|---|---|---|
| file | string | URL для скачивания файла (обязательный параметр) |
| file_name | string | Наименование файла |
| file_size | int | Размер файла, исчисляемое в байтах |
| text | string | Текст прикрепленный к сообщению |
6. LOCATION#
- Пример
"message": { "type": "LOCATION", "latitude": 53.3416484, "longitude": -6.2868531 }
| Наименование | Тип | Описание |
|---|---|---|
| latitude | float | Значение широты (обязательный параметр)) |
| longitude | float | Значение долготы (обязательный параметр) |
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 клиентом Уникальный в рамках аккаунта |
INIT_RATE#
Бот-провайдер запрашивает показ формы для оценки качества обслуживания в диалоге.
Обратите внимание, что оценка, полученная вызовом этого метода, не сохраняется в Jivo, а передается на хранение и использование бот-провайдеру.
Пример
{ "event": "INIT_RATE", "id": "123e4567-e89b-12d3-a456-426655440000", "client_id": "2", "chat_id": "4" }
Параметры события
| Наименование | Тип | Описание |
|---|---|---|
| id | string | Уникальный идентификатор события, используется для логирования и дебага |
| client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
| chat_id | string | Идентификатор чата, в котором введется диалог 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 }
| Наименование | Тип | Описание |
|---|---|---|
| id | string | Уникальный идентификатор события, используется для логирования и дебага |
| client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
| chat_id | string | Идентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта |
| agents_online | boolean | Индикатор статуса операторов (онлайн или офлайн) |
| sender | object | Информация о клиенте: id - client_id (int), name - имя клиента (string) |
| channel | object | Информация о канале, в котором пришло сообщение: id - уникальный идентификатор канала (string), type - тип канала (string) |
| rate | object | rating - оценка, которую выставил клиент с возможными значениями: 'bad', 'badnormal', 'normal', 'goodnormal', 'good' (string); comment - комментарий к оценке (string) |
Схема интеграции бота и описание возможных ошибок доступны в статье в нашей базе знаний. Если у вас возникли какие-либо вопросы, вы можете прислать их в чате c нами или на почту info@jivo.ru.