Бот API Jivo

Вернуться к списку статей

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

Если у вас есть свой собственный бот на любой платформе и вы хотели бы его подключить к нам, то для получения идентификатора провайдера - напишите нам.

Обмен данными

Инициатором обмена является Jivo, это происходит при входящем сообщение от клиента. Обмен событиями с бот-провайдерам происходит c помощью механизма webhooks. Все события от Jivo отправляются на endpoint провайдера, в ответ провайдер отправляет события на endpoint Jivo.

Image1

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

Endpoint url бот-провайдера формируется на его усмотрение, endpoint Jivo формируется следующим образом: bot.jivosite.com/webhooks/{provider_id} , где provider_id уникальный идентификатор провайдера, выдается для каждого провайдера отдельно.

Коды ответа

Ниже в таблице приведен список возможных кодов ответа от 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
...


Авторизация

Поверх аутентификации, опционально можно использовать дополнительную меру защиты в виде авторизационного токена, который выдается бот-провайдером для Jivo и имеет ограниченное время жизни. Для этого Jivo сначала получает временный токен доступа в обмен на secret и client_id, после чего он передается при каждом обращение к бот-провайдеру и обратно в заголовке Authorization. Пример:

POST https://bot-provider-endpoint.com/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
Authorization: 92753d11-4aef-459a-8d45-1c1faabb6e36

...

POST https://bot.jivosite.com/providers/Ee0CRkyDAp/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
Authorization: 92753d11-4aef-459a-8d45-1c1faabb6e36
...


Типы событий

Тип сообщений Направление Описание
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_UNAVAILABLE Jivo API → Bot-Provider Событие о том, что в данный момент нет ни одного доступного оператора в сети, которые могли бы принять чат.

CLIENT_MESSAGE

Сценарий: бот-оператор подключен к каналу связи, клиент пишет сообщение, Jivo передает сообщение к бот-провайдеру, сообщение обрабатывается и возвращается ответ в зависимости от сценария.

Image2

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

Наименование Тип Описание
id String Уникальный идентификатор события, используется для логирования и отладки
client_id String Идентификатор пользователя, который пишет в один из каналов клиента Jivo. Уникальный в рамках аккаунта клиента
chat_id String Идентификатор чата, в котором введется диалог пользователя и оператора. Уникальный в рамках аккаунта клиента
message Message Сообщение клиента

Пример

{
  event: "CLIENT_MESSAGE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123",
  message: {
    type: "TEXT",
    text: "Здравствуйте!Сколько стоит доставка?",
    timestamp: 1583910736
  }
}

BOT_MESSAGE

Сценарий: клиент пишет сообщение, Jivo передает сообщение к бот-провайдеру, сообщение обрабатывается, бот отвечает заготовленным сообщением, оно отправляется клиенту.

Image3

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

Наименование Тип Описание
id String Уникальный идентификатор события, используется для логирования и отладки
chat_id String Идентификатор чата, в котором введется диалог пользователя и оператора. Уникальный в рамках аккаунта клиента
message Message Cсообщений от бота

Пример

{
  event: "BOT_MESSAGE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  message: {
    type: "BUTTONS",
      title: "Вас интересует доставка в пределах МКАД?",
      text: "Вас интересует доставка в пределах МКАД? Да / Нет"
      timestamp: 1583910736,
      buttons: [
        {
          text: "Да",
          id: 1,
        }, {
          text: "Нет",
          id: 2
        }
      ]
  }
}

INVITE_AGENT

Сценарий: клиент пишет сообщение, Jivo передает сообщение к бот-провайдеру, сообщение обрабатывается, у бота нет заготовленного ответа, он переводит диалог на оператора.

Image4

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

Наименование Тип Описание
id String Уникальный идентификатор события, используется для логирования и отладки
client_id String Идентификатор пользователя, который пишет в один из каналов клиента Jivo. Уникальный в рамках аккаунта клиента
chat_id String Идентификатор чата, в котором введется диалог пользователя и оператора. Уникальный в рамках аккаунта клиента

Пример

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

AGENT_JOINED

Сценарий: клиент пишет сообщение, Jivo передает сообщение к бот-провайдеру, сообщение обрабатывается, у бота нет заготовленного ответа, он переводит диалог на оператора, оператор подключается.

Image5

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

Наименование Тип Описание
id String Уникальный идентификатор события, используется для логирования и отладки
client_id String Идентификатор пользователя, который пишет в один из каналов клиента Jivo. Уникальный в рамках аккаунта клиента
chat_id String Идентификатор чата, в котором введется диалог пользователя и оператора. Уникальный в рамках аккаунта клиента

Пример

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

AGENT_UNAVAILABLE

Сценарий: бот-провайдер переводит чат на оператора, но доступных операторов в сети нет, тогда по сценарию бота, он отправляет сообщение с просьбой оставить свои контактные данные.

Image8

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

Наименование Тип Описание
id String Уникальный идентификатор события, используется для логирования и отладки
chat_id String Идентификатор чата, в котором введется диалог пользователя и оператора. Уникальный в рамках аккаунта клиента
client_id String Идентификатор пользователя, который пишет в один из каналов клиента Jivo. Уникальный в рамках аккаунта клиента

Пример

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

Типы сообщений

Тип сообщений Описание
TEXT Простое, текстовое сообщение
MARKDOWN Текстовое сообщение в формате Markdown
BUTTONS Варианты ответа в виде кнопок

TEXT

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

Наименование Тип Описание
text String Текст сообщения
button_id String Идентификатор кнопки, на которую нажал пользователь
timestamp String Временная метка создания сообщения, unix time

Пример

{
  type: "TEXT",
  text: "Здравствуйте!",
  button_id: "123",
  timestamp: 1583910736
}

MARKDOWN

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

Наименование Тип Описание
content String Сообщение в формате Markdown. В первой версии: link, bold, italic
text String Текстовый фаллбек для каналов связи, которые не поддерживают данный тип сообщений, иначе сообщение не будет отправлено клиенту.
button_id String Идентификатор кнопки, на которую нажал пользователь
timestamp String Временная метка создания сообщения, unix time

Пример

{
  type: "MARKDOWN",
  content: "Чтобы отключить **PUSH-уведомления** выполните действия описанные в [инструкции](https://site.com/page_url)",
  text: "Чтобы отключить PUSH-уведомления выполните действия описанные в инструкции https://site.com/page_url",
  timestamp: 1583910736
}

BUTTONS

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

Наименование Тип Описание
buttons Array<button> Набор кнопок с заготовленными ответами, максимум 3 кнопки.
title String Текстовый заголовок для кнопок
text String Текстовый фаллбек для каналов связи, которые не поддерживают данный тип сообщений, иначе сообщение не будет отправлено клиенту.
button.text String Текст заготовленного ответа
button.id String Идентификатор заготовленного ответа
timestamp String Временная метка создания сообщения, unix time

Пример

{
  type: "BUTTONS",
  title: "Укажите желаемую службу доставки?"
  text: "Укажите желаемую службу доставки? Доступны ПЭК и Boxberry.",
  buttons: [
    {
      text: "ПЭК",
      id: "1"
    }, 
    {
      text: "Boxberry",
      id:"2"
    }
  ],
  timestamp: 1583910736
}

Есть вопросы? Спросите техподдержку в чате на сайте, мы всегда рады помочь. Работаем 24 часа 7 дней в неделю.