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 к пользовательскому серверу и обратно.

ПолеТипОписание
senderUserОтправитель сообщения
recipientUserПолучатель сообщения
messageMessageСообщение

User

ПолеТипОписаниеМаксимальный размер
idstringИдентификатор клиента, обязательный параметр при отправке событий в Jivo sender.id и при получении событий от Jivo recipient.id255 символов
namestringИмя пользователя255 символов
photostringURL аватара пользователя, допустимые схемы https или http2048 символов
urlstringURL страницы пользователя, допустимые схемы https или http2048 символов
emailstringЭлектронная почта пользователя255 символов
phonestringТелефонный номер пользователя2-15 символов
invitestringТекст приглашения клиента1000 символов
groupstringОтдел в который обращается клиент10 цифр
intentstringТема обращения клиента255 символов
crm_linkstringURL клиента в CRM-системе2048 символов

Message

ПолеТипОписаниеМаксимальный размер
typestringТип сообщения, обязательный параметрОграничен допустимыми значениями, варианты смотреть в таблице
idstringИдентификатор сообщения, необходим если требуется изменить статус сообщения после его отправки500 символов
datenumberВремя создания/отправки сообщения, целое числоОграничено разумными пределами величины UNIX-время
filestringURL медиа-данных2048 символов, допустимая схема https или http
thumbstringURL изображения предварительного просмотра для медиа-данных2048 символов, допустимая схема https или http
file_sizenumberРазмер медиа-данных в октетах (байтах)Целое положительное число, ограничено возможностями клиентских приложений
widthnumberШирина изображения или видео в пикселахЦелое положительное число, ограничено возможностями клиентских приложений
heightnumberВысота изображения или видео в пикселахЦелое положительное число, ограничено возможностями клиентских приложений
file_namestringИмя файла медиа-данных255 символов, возможна несовместимость с устаревшими файловыми системами!
mime_typestringMIME-тип медиа-данныхОграничено списком допустимых значений
textstringТекст сообщенияРекомендуется ограничить длину 1000 символов, при превышении, остатки текста будут досланы отдельными текстовыми сообщениями
titlestringЗаголовок сообщения255 символов
latitudenumberШирота местоположения, вещественное числоот -90.0000 до +90.0000
longitudenumberДолгота местоположения, вещественное числоот -180.0000 до +180.0000
valuenumberЧисло, обычно используется в оценке чаталюбое число
keyboard[]KeyМассив структур Key7 клавиш
multiplebooleanДопустимость множественного выбора на клавиатуре, логическоеtrue или false

Key

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

ПолеТипОписаниеМаксимальный размер
textstringТекст клавиши100 символов
imagestringURL изображения (схема https или http)2048 символов
titlestringЗаголовок или всплывающая подсказка клавиши100 символов
idstringИдентификатор клавиши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.

← Webhooks API