Бот API Jivo
Бот API позволяет подключать бот-платформы к любым диалогам в Jivo: чат на сайте, мессенджеры и социальные сети. При добавлении бота все диалоги будут сперва отправляться бот-провайдеру для обработки.
Если у вас есть свой собственный бот на любой платформе и вы хотели бы его подключить к нам, для получения идентификатора провайдера — напишите нам на info@jivo.ru с почты администратора вашего аккаунта Jivo.
В письме укажите:
- Адрес вашего сервера, куда мы будем отправлять события
- Токен бота
- Канал связи, на который нужно будет назначить бота
Обмен данными
Инициатором обмена является Jivo, это происходит при входящем сообщении от клиента. Обмен событиями с бот-провайдером происходит c помощью механизма webhooks. Все события от Jivo отправляются на endpoint провайдера, в ответ провайдер отправляет события на endpoint Jivo.
Все события от Jivo к бот-провайдеру и обратно отправляются в виде HTTPS-запросов, методом POST в формате application/json. Timeout запроса составляет 3 секунды, количество повторных попыток равно 2, до тех пор, пока не будет получен штатный успешный ответ, иначе клиент переводится на оператора. Это дает 9 секунд на обновление ПО на сервере, чего хватает в большинстве случаев.
Также после отправки запроса от Jivo к бот-провайдеру запускается таймер в 15 секунд для формирования ответа. Если в течение этого времени не приходит событие BOT_MESSAGE, в диалог приглашается оператор.
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_UNAVAILABLE | Jivo API → Bot-Provider | Событие о том, что в данный момент нет ни одного доступного оператора в сети, которые могли бы принять чат. |
| CHAT_CLOSED | Jivo API → Bot-Provider | Событие о закрытии чата |
| INIT_RATE | Bot-Provider → Jivo API | Бот-провайдер запрашивает показ формы для оценки качества обслуживания в диалоге |
| CLIENT_RATED | Jivo API → Bot-Provider | Клиент оставил оценку в форме, вызванной методом INIT_RATE |
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": "MARKDOWN".
Пример
{
"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"
}
Событие 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_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"
}
CHAT_CLOSED
Отправляется, если чат был принят оператором или автоматически закрылся по таймауту. Если бот-провайдеру поступило это событие, бот больше не сможет отправлять сообщения в этот чат.
Параметры события:
| Наименование | Тип | Описание |
| id | String | Уникальный идентификатор события, используется для логирования и отладки |
| chat_id | String | Идентификатор чата, в котором введется диалог пользователя и оператора. Уникальный в рамках аккаунта клиента |
| client_id | String | Идентификатор пользователя, который пишет в один из каналов клиента Jivo. Уникальный в рамках аккаунта клиента |
Пример
{ "id": "f9e59d98-48bc-11ed-896a-47ed16cbbd46", "chat_id": "2043", "client_id": "1236", "event": "CHAT_CLOSED" }
Ограничение числа запросов
Так как бот-провайдер может сделать бесконечный цикл сообщений и ответов, а также начать присылать больше сообщений, чем требуется, в Jivo API есть ограничение на число запросов в час, которые можно принять от каждого бота. При достижении лимита при запросе Bot Provider -> Jivo API, Jivo API выведет следующий ответ:
Пример:
Status: 429
{
"error": {
"code": "about:blank",
"message": "Call is blocked"
}
}
После этого прием сообщений будет ограничен на один час. Через час Jivo API начнет принимать новые сообщения от бота.
Работаем 24 часа 7 дней в неделю.