Бот API Jivo

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

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

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

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

Все события от 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
...

Типы событий

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

CLIENT_MESSAGE

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

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

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

{
 "id":"996344da-d8f4-11ec-9aaf-c5bde7170335",
 "site_id":"1153381",
 "client_id":"3209",
 "chat_id":"4209",
 "agents_online":true,
 "sender":{"id":2108,"url":"https://testwebsite.ru/",
 "has_contacts":false},
 "message":{"type":"TEXT",
 "text":"Текст сообщения посетителя",
 "timestamp":1653135123},
 "channel":{"id":"Qy4NGbfuDt",
 "type":"widget"},
 "event":"CLIENT_MESSAGE"
}

BOT_MESSAGE

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

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

Варианты событий Бота

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

Событие BOT_MESSAGE тип TEXT

Наименование	Тип	Описание
Text	String	Текст сообщения
timestamp	String	Временная метка создания сообщения, unix time

Пример

{
 "id":"996344da-d8f4-11ec-9aaf-c5bde7170335",
    "event":"BOT_MESSAGE",
    "message":
    {"type":"TEXT",
    "text":"Конечно, я готов вам помочь. Какой у вас вопрос?",
    "timestamp":1653127681833},
    "client_id":"3209","chat_id":"4209"
}

Событие BOT_MESSAGE тип BUTTONS

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

{
 "id":"996344da-d8f4-11ec-9aaf-c5bde7170335",
 "event":"BOT_MESSAGE",
 "message":{"type":"BUTTONS","text":"Добрый день!\nЧем я могу быть полезен?",
 "timestamp":1653134682812,
 "title":"Добрый день!\nЧем я могу быть полезен?","buttons":
    [{"id":1,"text":"Когда доставят заказ /Отменить"},
    {"id":2,"text":"Доставка, Примерка, Размеры"},
    {"id":3,"text":"Возврат, Обмен"}]},
    "client_id":"3209","chat_id":"4209"
}

Событие BOT_MESSAGE тип Markdown

• Есть возможность включить поддержку кодировки markdown в событиях "type": "TEXT", для этого напишите запрос с почты администратора Jivo на почту info@jivosite.com.

Пример

{
 "id":"996344da-d8f4-11ec-9aaf-c5bde7170335",
 "event":"BOT_MESSAGE",
 "message":
 {"type":"MARKDOWN",
 "content": "Чтобы отключить **PUSH-уведомления** выполните действия описанные в [инструкции](https://site.com/page_url)",
 "text": "Чтобы отключить PUSH-уведомления выполните действия описанные в инструкции https://site.com/page_url",
 "timestamp":1653127681833},
 "client_id":"2160","chat_id":"4209"
}

Событие CLIENT_INFO

Кейс: клиент пишет сообщение, Jivo проксирует сообщение к бот-провайдеру, сообщение обрабатывается, находятся (или запрашиваются) контакты клиента, бот отвечает заготовленным сообщением с контактными данными клиента. Они появляются в Jivo, в приложении оператора, в диалоге, в правой части, как если бы клиент заполнил форму контактов

Пример

{
 "event": "CLIENT_INFO",
 "id": "996344da-d8f4-11ec-9aaf-c5bde7170335",
 "client_id":"3209",
 "client": {
 "email": "example@post.ru",
 "phone": "71234567",
 "name": "Ivan"
  }
}

Событие INVITE_AGENT

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

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

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

Пример

{
  "id":"996344da-d8f4-11ec-9aaf-c5bde7170335",
    "event":"INVITE_AGENT",
    "client_id":"3209","chat_id":"4209"
    }

Событие AGENT_JOINED

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

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

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

Пример

{
  event: "AGENT_JOINED",
  id:"996344da-d8f4-11ec-9aaf-c5bde7170335",
  client_id: "3209",
  chat_id: "4209"
}

Событие AGENT_UNAVAILABLE

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

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

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

Пример:

{
  event: "AGENT_UNAVAILABLE",
  id:"996344da-d8f4-11ec-9aaf-c5bde7170335",
  chat_id: "4209",
  client_id: "3209"
}

Ограничение числа запросов

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

Пример:

Status: 429
{
   "error": {
       "code": "about:blank",
       "message": "Call is blocked"
   }
}

После этого прием сообщений будет ограничен на один час. По окончании часа Jivo API начнет принимать новые сообщения от бота.