Категории

Документация

Bot API

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

Все события от Jivo к бот-провайдеру и обратно отправляются в виде HTTPS-запросов, методом POST в формате application/json. Timeout запроса составляет 3 секунды, количество повторных попыток равно 2, до тех пор, пока не будет получен штатный успешный ответ, иначе клиент переводится на оператора. Это дает 9 секунд на обновление ПО на сервере, чего хватает в большинстве случаев.

Типы событий

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

CLIENT_MESSAGE

Используется для передачи сообщения клиента бот-провайдеру. Запрос с сообщением обрабатывается, и в диалог возвращается ответ бота.

Пример

{
  "id": "9661ab9c-48b0-11ed-a3d6-859398ff9bd9",
  "site_id": "123456",
  "client_id": "1233",
  "chat_id": "2037",
  "agents_online": true,
  "sender": {
    "id": 1233,
    "name": "John Smith",
    "url": "https://test.com",
    "has_contacts": true
  },
  "message": {
    "type": "TEXT",
    "text": "Вы можете мне помочь?",
    "timestamp": 1665415879
  },
  "channel": {
    "id": "12345678",
    "type": "widget"
  },
  "event": "CLIENT_MESSAGE"
}

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

Наименование	Тип	Описание
id	string	Уникальный идентификатор события, используется для логирования и дебага
site_id	string	Идентификатор аккаунта Jivo, с которого пришёл запрос
client_id	string	Идентификатор клиента, который пишет в один из каналов Jivo `Уникальный в рамках аккаунта`
chat_id	string	Идентификатор чата, в котором ведется диалог `Уникальный в рамках аккаунта`
agents_online	boolean	Идентификатор статуса операторов (онлайн или офлайн)
sender	object	Информация о клиенте
message	object	Данные об отправленном сообщении
channel	object	Информация о канале, в котором было отправлено сообщение
event	string	Тип события

sender

Наименование	Тип	Описание
id	int	Идентификатор клиента (аналогично client_id)
user_token `необязательный`	string	Идентификатор пользователя, переданный через API-метод
name `необязательный`	string	Имя клиента
url	string	Адрес страницы, с которой написал клиент
has_contacts	boolean	Информирует о том, указаны ли у пользователя контактные данные

message

Наименование	Тип	Описание
type	string	Тип сообщения
text	string	Текст сообщения
timestamp	int	Метка времени

channel

Наименование	Тип	Описание
id	string	Идентификатор канала, с которого было отправлено сообщение клиента
type	string	Тип канала

BOT_MESSAGE

Используется для проксирования ответа бота в диалог клиенту. Отправляется от бот-провайдера в Jivo.

Пример

{   
  "id": "093e9c6a-48b6-11ed-907d-7d426317dad5",
  "client_id": "1235",
  "chat_id": "2041",
  "message": {
    "type": "BUTTONS",
      "title": "Вас интересует доставка в пределах МКАД?",
      "text": "Вас интересует доставка в пределах МКАД? Да / Нет",
      "timestamp": 1583910736,
      "force_reply": true,
      "buttons": [
        {
          "text": "Да",
          "id": 1
        }, {
          "text": "Нет",
          "id": 2
        }
      ]
  },
  "event": "BOT_MESSAGE",
}

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

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

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

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

1. TEXT

Пример

 {
   "message": {
     "type": "TEXT",
     "text": "Здравствуйте! Чем могу вам помочь? ",
     "timestamp": 1653127681833
  },
 }

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

2. MARKDOWN

Пример

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

Наименование	Тип	Описание
сontent	string	Сообщение в формате Markdown (поддерживается link, bold, italic)
text	string	Текстовый fallback для каналов связи, которые не поддерживают данный тип сообщений, иначе сообщение не будет отправлено клиенту
timestamp	int	Временная метка создания сообщения, unix time

3. BUTTONS

Пример

  "message": {
    "type": "BUTTONS",
    "title": "Вас интересует доставка в пределах МКАД?",
    "text": "Вас интересует доставка в пределах МКАД? Выберите да или нет",
    "force_reply": true,
    "buttons": [
      {
        "text": "Да",
        "id": 1
      }, {
        "text": "Нет",
        "id": 2
      }
    ],
    "timestamp": 1583910736,
  }

Наименование	Тип	Описание
title	string	Текстовый заголовок для кнопок
text	string	Текстовый fallback для каналов связи, которые не поддерживают данный тип сообщений, иначе сообщение не будет отправлено клиенту
force_reply `Необязательный`	boolean	Если приходит true, поле ввода сообщения в виджете блокируется, чтобы пользователь выбрал одну из отправленных кнопок
buttons	array	Набор кнопок с заготовленными ответами
buttons.text	string	Текст заготовленного ответа
button.id	string	Идентификатор отправленной кнопки

INVITE_AGENT

Отправляется от бот-провайдера в Jivo в случае, если необходимо перевести диалог на оператора.

Пример

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

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

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

AGENT_UNAVAILABLE

Бот переводит чат на оператора. Если операторов в сети нет, то бот-провайдеру отправляется соответствующее событие. В этом случае бот может продолжить общение с клиентом - например, запросить контакты.

Пример

{
  "id": "f061d944-48bc-11ed-a11a-9b4e3e49df1b",
  "chat_id": "2043",
  "client_id": "1236",
  "event": "AGENT_UNAVAILABLE"
}

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

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

CHAT_CLOSED

Отправляется, если чат был принят оператором или автоматически закрылся по таймауту. Если бот-провайдеру поступило это событие, бот больше не сможет отправлять сообщения в этот чат.

Пример

{
  "id": "f9e59d98-48bc-11ed-896a-47ed16cbbd46",
  "chat_id": "2043",
  "client_id": "1236",
  "event": "CHAT_CLOSED"
}

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

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

CLIENT_INFO

Используется для передачи контактных данных клиента от бот-провайдера в Jivo в ответ на сообщение клиента. Контакты отобразятся в приложении Jivo в диалоге в информационной панели справа.

Пример

{
 "id": "996344da-d8f4-11ec-9aaf-c5bde7170335",
 "client_id": "1237",
 "client": {
    "email": "example@post.ru",
    "phone": "89754154877",
    "name": "Иван"
  },
  "event": "CLIENT_INFO"
}

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

Наименование	Тип	Описание
id	string	Уникальный идентификатор события, используется для логирования и дебага
client_id	string	Идентификатор клиента, который пишет в один из каналов Jivo `Уникальный в рамках аккаунта`
client	object	Контактная информация о клиенте (email, phone, name)

Схема интеграции бота и описание возможных ошибок доступны в статье в нашей базе знаний. Если у вас возникли какие-либо вопросы, вы можете прислать их в чате c нами или на почту info@jivo.ru.