Бот 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 и бот-провайдера:

В случае возникновения нештатной ситуации, в тело ответа рекомендуется передавать информацию об ошибке в следующем формате:

{
  "error" :
    {
      "code": "<код ошибки>",
      "message": "<human-readable сообщение ошибки>"
    }
}

Коды ошибок

Аутентификация

Аутентификация клиента бот-провайдера от которого идет обращение в 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 передает сообщение к бот-провайдеру, сообщение обрабатывается и возвращается ответ в зависимости от сценария.

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

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

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

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

Пример

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

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

{
 "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":"996344da-d8f4-11ec-9aaf-c5bde7170335",
    "event":"INVITE_AGENT",
    "client_id":"3209","chat_id":"4209"
    }

Событие AGENT_JOINED

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

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

Пример

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

Событие AGENT_UNAVAILABLE

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

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

Пример:

{
  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 начнет принимать новые сообщения от бота.