Чат API Jivo

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

Для интеграции используется механизм Webhooks. Jivo предоставляет endpoint для получения статуса канала и для передачи сообщения клиента, а на стороне интегрируемой системы должен быть endpoint для передачи ответа оператора клиенту.

Endpoint Jivo содержит случайную строку для защиты от перебора, а также идентификатор канала JIVO_PUBLIC_ID.

Общий принцип работы

Основной workflow интеграции

title Jivo-Webhooks Channel

Customer API->JivoSite: Channel Status HTTP GET
JivoSite->Customer API: Online (1)
Customer API->User: Show custom chat window
User->Customer API: Type User Message
Customer API->JivoSite: User Message HTTP POST
JivoSite->Agent: User Message
Agent->JivoSite: Agent Message
JivoSite->Customer API: Agent Message HTTP POST
Customer API->User: Draw Agent Message

Описание протокола

Customer API->JivoSite: Chat Status

GET https://wh.jivosite.com/<some random string>/JIVO_PUBLIC_ID/status

Штатный ответ 200 OK, с телом в виде целого числа:

0 - чат недоступен. Операторы не в сети или чат удален с сайта
1 - чат доступен. Операторы в сети

В случае, если в Jivo нет канала с JIVO_PUBLIC_ID, сервер вернёт HTTP-статус 404.

Если ответ не штатный, желательно сразу нас уведомить.

Customer API->JivoSite: User Message

POST https://wh.jivosite.com/<some random string>/JIVO_PUBLIC_ID
{
   "sender" :
   {
      "id"    : "12345",
      "name"  : "John Doe",
      "photo" : "https://example.com/photo.jpg",
      "url"   : "https://ya.ru/simple/page.html",
      "phone" : "12345678901",
      "email" : "john@doe.сom",
      "invite" : "Hello! Can I help you?"
   },
   "message" :
   {
      "type" : "text",
      "id"   : "customer_message_id",
      "text" : "User Message Text"
   }
}

sender.id - (обязательный, строка) идентификатор клиента в Customer API. Если поле отсутствует, сообщение не будет передано

sender.name, phone, email - опциональные поля (string). Если Jivo их получит, то отобразит оператору, если нет - то чат будет с Анонимусом. Значения могут быть обновлены в ходе чата.

sender.photo - опциональная ссылка на картинку-аватар клиента. Ссылка должна начинаться с "http://" либо с "https://". Рекомендуемый размер картинки - 128*128 px png/jpg/gif. Приложение будет пытаться отобразить и другие картинки, но корректность отображения не гарантируется.

sender.invite - опциональный текст приглашения. Работает аналогично функции "приглашение от имени оператора" в виджете. Логика отображения приглашения реализуется в чате на стороне Customer API, при этом текст приглашения можно передать в поле sender.invite и операторы увидят его, и смогут понять в каком контексте к ним обращается клиент.

message.id - идентификатор сообщения в Customer API. Он не будет виден нигде, кроме логов. Будет использоваться в следующих версиях для уведомления о доставке/прочтении.

message.type - (required) константа "text" (список значений в таблице ниже).

message.text - (required для type==text) - строка сообщения клиента, до 1000 символов. Если будет больше - можем разрезать.

Штатный ответ 200 OK. Если код ответа отличается от 200, желательно сразу нас уведомить.

В случае, если в Jivo нет канала с JIVO_PUBLIC_ID, сервер вернёт HTTP-статус 404.

JivoSite->Customer API: Agent Message

POST <Customer API HTTPS-endpoint URL>/
{
    "sender" : {
   	 "name" : "Agent Name",
   	 "photo" : "Agent Photo URL"
    },
    "recipient" : {
   	 "id" : "12345"
    },
    "message" : {
  	"type" : "text",
  	"id"   : "jivo_message_id",
  	"text" : "Agent Message Text"
    }
}

sender.name - имя оператора, написавшего ответ

sender.photo - ссылка на картинку - аватар оператора

recipient.id - идентификатор клиента в Customer API. Мы его получим из входящего сообщения и передадим обратно в неизменном виде

message.id - идентификатор сообщения в Jivo. Может использоваться в дальнейшем для уведомлений о доставке/прочтении.

Штатный ответ 200 OK.

Тело ответа в формате json:

{
"result" : "ok"
}

либо

{
"error" :
{
		"code" : <код ошибки>,
	"message" : <human-readable сообщение ошибки>"
}
}

Сообщение ошибки будет отображаться оператору в диалоге Jivo. Может не отображаться в зависимости от кода ошибки.

Уведомление о наборе сообщения

Для уведомления о наборе сообщения используется передача сообщения с указанием type:
type:"typein" - начало набора сообщения
type: "typeout" - окончание набора сообщения.
Другие поля в сообщении с таким "type" игнорируются.

Работает идентично в обе стороны, как от jivo в customer api, так и от customer api в jivo.

Передача мультимедиа-сообщений

Мультимедиа-сообщения передаются точно так же, как и текстовые сообщения, но имеют особый type и дополнительные поля. Состав обязательных полей и значение поля type для каждого поддерживаемого типа мультимедиа приведены ниже.

Значение поля type	Обязательные дополнительные поля	Тип мультимедиа
video	file, file_name, file_size	видео
audio	file, file_name, file_size	аудио
voice	file, file_name, file_size	голосовое сообщ.
photo	file, file_name, file_size	изображение
sticker	file, file_name, file_size	стикер
document	file, file_name, file_size	файл (просто файл)
location	latitude, longitude	гео-расположение

Опциональные поля мультимедиа сообщений приведены ниже:

Поле мультимедиа-сообщения	Описание
string file	http(s)-ссылка на сам файл
string thumb	http(s)-ссылка на изображение предпросмотра файла (w320px)
string emoji	возможная замена медиа на символ юникода
number file_size	размер файла в байтах, целое положительное
string file_name	имя файла определенное пользователем
number duration	продолжительность потока в секундах, целое положительное
number width	ширина в пикселях, целое положительное
number height	высота в пикселах, целое положительное
string text	текст сообщения или комментария
string performer	автор (композитор, исполнитель и пр.)
string title	название
number latitude	широта местоположения, вещественное
number longitude	долгота местоположения, вещественное

Повторная отправка сообщений

На сервер Customer API события, в виде http(s)-запросов, отправляются с повтором 3 раза каждые 3 секунды до тех пор, пока не будет получен валидный положительный ответ. Это дает 6 секунд на обновление ПО на сервере, чего хватает в большинстве случаев. При недоступности сервера событие ошибки вернется через 9 секунд. Такие настройки по умолчанию позволяют оперативно получить ответ отправителю. В случае таймаута или ошибки Customer API оператор увидит сообщение об ошибке в ленте чата.

Chunked-запрос

Jivo может отправлять запросы на Customer API как с полем Content-Length, так и в кодировке Chunked.