Категории

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

Chat API

В этой памятке описан способ обмена событиями между серверами по Chat-каналу при интеграции с Jivo. Чат API канал асинхронный двунаправленный, для полной реализации необходим пользовательский сервер, способный принимать и отправлять события.

Протокол канала

Транспортным протоколом для передачи событий является HTTPS (на этапе разработки допускается использовать HTTP). Событие содержится в теле POST-запроса в формате JSON (кодировка текста в этом формате - UTF-8), запрос должен иметь соответствующий заголовок Content-Type: application/json; charset=utf-8. Структура событий описана далее. Варианты ответов делятся на 3 группы по HTTP-коду ответа.

Код	Описание	Действие
2xx	Успех. Событие принято в обработку	Сообщить пользователю об успехе доставки
4xx	Ошибка запроса. Событие отклонено	В теле ответа с таким кодом, может быть текст описания ошибки (тип содержимого Content-Type: text/plain; charset=utf-8). Повторно отправлять это событие не следует. Необходим анализ и исправление ошибки программы или настроек канала. Информировать пользователя об ошибке доставки события
Любой другой HTTP-код или ошибка подключения	Принять запрос невозможно в данный момент. Событие не принято	В случае HTTP-кода 5xx или при неудачном подключении, рекомендуется повторить запрос до 3х раз с промежутком 3-60 секунд. Информировать пользователя о временной невозможности доставки события. Связаться с поддержкой сервера

Создание канала

Для создания Chat-канала в Jivo следует использовать приложение. После создания станет доступен URL для отправки событий в Jivo, например: https://wh.jivosite.com/foo/bar. Для приема сообщений от Jivo необходимо реализовать пользовательский сервер и добавить URL, на который он будет принимать события, в настройки канала в приложении.

Статус канала

Если к URL для отправки событий в Jivo добавить в конце пути сегмент /status, например https://wh.jivosite.com/foo/bar/status, то в теле ответа (при успешном овете с кодом 2xx) на GET-запрос по полученному URL будет статус канала, означающий отсутствие собеседников на канале когда ответ 0, либо наличие собеседников при ответе 1 или любом другом.

Структура событий

Протокол симметричный, структура одинакова для событий от Jivo к пользовательскому серверу и обратно.

Поле	Тип	Описание
sender	User	Отправитель сообщения
recipient	User	Получатель сообщения
message	Message	Сообщение

User

Поле	Тип	Описание	Максимальный размер
id	string	Идентификатор клиента, обязательный параметр при отправке событий в Jivo sender.id и при получении событий от Jivo recipient.id	255 символов
name	string	Имя пользователя	255 символов
photo	string	URL аватара пользователя, допустимые схемы https или http	2048 символов
url	string	URL страницы пользователя, допустимые схемы https или http	2048 символов
email	string	Электронная почта пользователя	255 символов
phone	string	Телефонный номер пользователя	2-15 символов
invite	string	Текст приглашения клиента	1000 символов
group	string	Отдел, в который обращается клиент	10 цифр
intent	string	Тема обращения клиента	255 символов
crm_link	string	URL клиента в CRM-системе	2048 символов

Message

Поле	Тип	Описание	Максимальный размер
type	string	Тип сообщения, обязательный параметр	Ограничен допустимыми значениями, варианты смотреть в таблице
id	string	Идентификатор сообщения, необходим если требуется изменить статус сообщения после его отправки	500 символов
date	number	Время создания/отправки сообщения, целое число	Ограничено разумными пределами величины UNIX-время
file	string	URL медиа-данных	2048 символов, допустимая схема https или http
thumb	string	URL изображения предварительного просмотра для медиа-данных	2048 символов, допустимая схема https или http
file_size	number	Размер медиа-данных в октетах (байтах)	Целое положительное число, ограничено возможностями клиентских приложений
width	number	Ширина изображения или видео в пикселах	Целое положительное число, ограничено возможностями клиентских приложений
height	number	Высота изображения или видео в пикселах	Целое положительное число, ограничено возможностями клиентских приложений
file_name	string	Имя файла медиа-данных	255 символов, возможна несовместимость с устаревшими файловыми системами!
mime_type	string	MIME-тип медиа-данных	Ограничено списком допустимых значений
text	string	Текст сообщения	Рекомендуется ограничить длину 1000 символов, при превышении, остатки текста будут досланы отдельными текстовыми сообщениями
title	string	Заголовок сообщения	255 символов
latitude	number	Широта местоположения, вещественное число	от -90.0000 до +90.0000
longitude	number	Долгота местоположения, вещественное число	от -180.0000 до +180.0000
value	number	Число, обычно используется в оценке чата	любое число
keyboard	[]Key	Массив структур Key	7 клавиш
multiple	boolean	Допустимость множественного выбора на клавиатуре, логическое	true или false

Key

Обязательным для клавиши является наличие одного поля структуры, как в запросе keyboard так и в ответе. Подробнее в примере. Приоритет полей для отображения пользователю записан в таблице по убыванию.

Поле	Тип	Описание	Максимальный размер
text	string	Текст клавиши	100 символов
image	string	URL изображения (схема https или http)	2048 символов
title	string	Заголовок или всплывающая подсказка клавиши	100 символов
id	string	Идентификатор клавиши	500 символов

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

Тип	Описание	Обязательные поля
text	Текстовое сообщение	text
photo	Изображение	file
sticker	Стикер	file
video	Видео-сообщение	file
audio	Звуковое сообщение	file
document	Документ или файл, в сообщении этого типа можно отправлять любые файлы, разрешенные для передачи в Jivo.	file
location	Местоположение	latitudelongitude
rate	Оценка чата	value
seen	Событие прочтения сообщения, в поле id необходимо указать идентификатор прочитанного сообщения	id
keyboard	Клавиатура с вариантами ответов, подробности в примере	keyboard
typein	Событие о наборе текста, в поле text этого сообщения можно записать набранный текст, чтобы он был виден пользователю Jivo. Отправлять это событие не чаще 1 раза в 5 секунд от одного клиента	-
start	Начало чата, предназначено для возобновления чата после команды stop без отправки сообщения клиентом	-
stop	Завершение чата, сигнал о том, что события по этому клиенту больше не принимаются	-

Примеры событий

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

Если для пользователя Jivo определено хоть одно свойство отправителя, в событие добавляется поле sender с этой информацией. Получатель сообщения идентифицируется полем recipient.id.

{
   "sender": {
      "id": "XXX",
      "name": "Консультант",
      "photo": "https://example.com/avatar.png",
      "email": "info@jivosite.com"
   },
   "recipient": {
      "id": "001"
   },
   "message": {
      "type": "text",
      "id":   "0000",
      "date": 946684800,
      "text": "Добрый день!"
   }
}

Клавиатура с вариантами ответов

Клавиатура может быть отправлена только от пользователя Jivo к клиенту:

{
   "recipient": {
      "id": "001"
   },
   "message": {
      "type":     "keyboard",
      "id":       "0009",
      "title":    "Опрос",
      "text":     "Быть или не быть?",
      "multiple": false,
      "keyboard": [
         {
            "id": "1",
            "text": "да"
         },
         {
            "id": "2",
            "text": "нет"
         },
         {
            "id": "X",
            "text": "надо подумать..."
         }
      ]
   }
}

Ожидается, что ответом клиента на такое сообщение будет один элемент из массива keyboard, если multiple != true:

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type":     "keyboard",
      "id":       "0009",
      "multiple": false,
      "keyboard": [
         {
            "id": "X",
            "text": "надо подумать..."
         }
      ]
   }
}

или несколько, в случае multiple = true.

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

Опрос

Быть или не быть?
   1) да
   2) нет
   X) надо подумать...

Ответом на сообщение keyboard может быть текстовое сообщение, например:

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type":  "text",
      "text":  "надо подумать..."
   }
}

Далее следуют примеры событий для отправки в Jivo.

Начало чата

При первом событии от клиента, рекомендуется заполнить структуру sender. Далее, достаточно поля sender.id, а остальные поля этой структуры можно заполнять только при их изменении.

{
   "sender": {
      "id":     "001",
      "name":   "Иван Иванович",
      "photo":  "https://example.com/me.jpg",
      "url":    "https://example.com/",
      "phone":  "+7(958)100-32-91",
      "email":  "me@example.com",
      "invite": "Здравствуйте! Могу вам чем то помочь?"
   },
   "message": {
      "type": "start"
   }
}

Текстовое сообщение

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type": "text",
      "id":   "0001",
      "date": 946684800,
      "text": "Добрый день!"
   }
}

Изображение

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type":      "photo",
      "id":        "0002",
      "date":      946684800,
      "file":      "https://example.com/image.png",
      "mime_type": "image/png",
      "file_name": "image.png",
      "file_size": 1024,
      "thumb":     "https://example.com/image_thumb.png",
      "width":     800,
      "height":    600,
      "title":     "Заголовок",
      "text":      "Комментарий к изображению."
   }
}

Стикер

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type":      "sticker",
      "id":        "0003",
      "date":      946684800,
      "file":      "https://example.com/sticker.gif",
      "mime_type": "image/gif",
      "file_name": "sticker.gif",
      "file_size": 1024,
      "width":     256,
      "height":    256
   }
}

Видео-сообщение

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type":      "video",
      "id":        "0004",
      "date":      946684800,
      "file":      "https://example.com/video.mp4",
      "mime_type": "video/mp4",
      "file_name": "video.mp4",
      "file_size": 1048576,
      "thumb":     "https://example.com/video_thumb.png",
      "width":     640,
      "height":    480,
      "title":     "Заголовок",
      "text":      "Комментарий к видео."
   }
}

Звуковое сообщение

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type":      "audio",
      "id":        "0005",
      "date":      946684800,
      "file":      "https://example.com/audio.mp3",
      "mime_type": "audio/mpeg",
      "file_name": "audio.mp3",
      "file_size": 2048,
      "title":     "Заголовок",
      "text":      "Комментарий к звуковому сообщению."
   }
}

Документ или файл

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type":      "document",
      "id":        "0006",
      "date":      946684800,
      "file":      "https://example.com/document.pdf",
      "mime_type": "application/pdf",
      "file_name": "document.pdf",
      "file_size": 512,
      "title":     "Заголовок",
      "text":      "Комментарий к документу."
   }
}

Местоположение

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type":      "location",
      "id":        "0007",
      "date":      946684800,
      "text":      "Это тут.",
      "latitude":  53.3416484,
      "longitude": -6.2868531
   }
}

Оценка чата

На данный момент используются 3 варианта значения поля value: 0 интерпретируется как отказ оценивать, положительное число - положительная оценка, отрицательное число - отрицательная оценка чата.

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type":  "rate",
      "id":    "0008",
      "value": 1
   }
}

Событие о наборе текста

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type": "typein",
      "text": "Подождите мину"
   }
}

Событие прочтения сообщения

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type": "seen",
      "id":   "0001"
   }
}

Завершение чата

{
   "sender": {
      "id": "001"
   },
   "message": {
      "type": "stop"
   }
}

Решение проблем

При обнаружении неточностей в этой памятке, либо при ее несоответствии действительности, просьба сообщить в чат поддержки Jivo или на email.