Chat API
В этой памятке описан способ обмена событиями между серверами по Chat-каналу при интеграции с Jivo. Chat-канал асинхронный двунаправленный, для полной реализации необходим пользовательский сервер, способный принимать и отправлять события.
Протокол канала
Транспортным протоколом для передачи событий является 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 символов |
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 | Завершение чата, сигнал о том, что события по этому клиенту больше не принимаются | - |
Примеры событий
Пример события от 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.