Jivo – бесплатный инструмент общения с клиентами на сайте, в Facebook, ВКонтакте, Одноклассниках, Viber и Telegram.
Добро пожаловать в Jivo!
Проверьте почту, мы отправили вам ссылку на регистрацию. Для установки 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
...
Поверх аутентификации, опционально можно использовать дополнительную меру защиты в виде авторизационного токена, который выдается бот-провайдером для 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 передает сообщение к бот-провайдеру, сообщение обрабатывается и возвращается ответ в зависимости от сценария.
Параметры события
Наименование | Тип | Описание |
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 передает сообщение к бот-провайдеру, сообщение обрабатывается, бот отвечает заготовленным сообщением, оно отправляется клиенту.
Параметры события
Наименование | Тип | Описание |
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 передает сообщение к бот-провайдеру, сообщение обрабатывается, у бота нет заготовленного ответа, он переводит диалог на оператора.
Параметры события
Наименование | Тип | Описание |
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 передает сообщение к бот-провайдеру, сообщение обрабатывается, у бота нет заготовленного ответа, он переводит диалог на оператора, оператор подключается.
Параметры события
Наименование | Тип | Описание |
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
Сценарий: бот-провайдер переводит чат на оператора, но доступных операторов в сети нет, тогда по сценарию бота, он отправляет сообщение с просьбой оставить свои контактные данные.
Параметры события
Наименование | Тип | Описание |
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
}