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_JOINED | Jivo API → Bot-Provider | К диалогу подключился оператор по инициативе бот-провайдера или клиента |
| AGENT_MESSAGE | Jivo API → Bot-Provider | Событие о новом сообщении от оператора клиенту, которое бот-провайдеру надо учесть в контексте диалога и модели обучения |
| 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 | Тип канала |
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 | Местоположение |
Передача сообщений типов VIDEO, PHOTO, AUDIO, VOICE, DOCUMENT недоступна по умолчанию, и включается по запросу для каждого бот-провайдера. Если вы поддерживаете методы передачи файлов и хотите реализовать ее, обратитесь в поддержку Jivo.
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_JOINED
Бот переводит чат на оператора.
Пример
{ "event": "AGENT_JOINED", "id": "123e4567-e89b-12d3-a456-426655440000", "client_id": "1234", "chat_id": "213123" "sender": { "id": 12, "name": "string" }, }
Параметры события
| Наименование | Тип | Описание |
|---|---|---|
| id | string | Уникальный идентификатор события, используется для логирования и дебага |
| client_id | string | Идентификатор клиента, который пишет в один из каналов Jivo Уникальный в рамках аккаунта |
| chat_id | string | Идентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта |
| sender | object | Информация об операторе |
AGENT_MESSAGE
Оператор отвечает в чате. Бот-провайдер получает возможность учитывать контекст общения и при возможности обучать AI-модель.
Пример
{ "event": “AGENT_MESSAGE“, "id": "123e4567-e89b-12d3-a456-426655440000", "chat_id": "213123", "answer_group_id": "1234", "answer_id": "1123", "sender": { "id": 12, "name": "string" }, "message": { "type": "TEXT", "text": "Здравствуйте! Сколько стоит доставка?", "timestamp": 1583910736 } }
Параметры события
| Наименование | Тип | Описание |
|---|---|---|
| id | string | Уникальный идентификатор события, используется для логирования и дебага |
| chat_id | string | Идентификатор чата, в котором введется диалог c клиентом Уникальный в рамках аккаунта |
| answer_group_id | string | Идентификатор группы вариантов, если они были показаны оператору, иначе — null |
| answer_id | string | Идентификатор выбранного варианта ответа предложенным ботом, иначе — null |
| answer_id | string | Идентификатор выбранного варианта ответа предложенным ботом, иначе — null |
| sender | object | Информация об операторе |
| message | object | Сообщение оператора для клиента |
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.