Категории

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

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	В запросе отсутствует обязательный параметр, либо используется неподдерживаемое значение параметра, содержится дубликат параметра, включено несколько наборов учетных данных, либо другие ошибки запроса.

Типы событий

Тип сообщений	Направление	Описание
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, ~~strikethrough~~ и image (inline) )
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.

Пример

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