Бот 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
...

Авторизация

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

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

Пример

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

BOT_MESSAGE

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

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

Пример

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

INVITE_AGENT

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

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

Пример

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

AGENT_JOINED

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

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

Пример

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

AGENT_UNAVAILABLE

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

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

Пример

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

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

TEXT

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

Пример

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

MARKDOWN

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

Пример

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

BUTTONS

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

Пример

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