Общайтесь с вашими клиентами в реальном времени и зарабатывайте больше

JivoSite – бесплатный инструмент общения с клиентами на сайте, в Facebook, ВКонтакте, Одноклассниках, Viber и Telegram.

Email введен неверно Что-то пошло не так. Пожалуйста, зайдите позже

Добро пожаловать в JivoSite!
Проверьте почту, мы отправили вам ссылку на регистрацию. Для установки Jivo вам понадобится компьютер.

Чат API JivoSite

Вернуться к списку статей

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

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

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

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

Pic1

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

Pic2

title JivoSite-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 - чат доступен. Операторы в сети

В случае, если в JivoSite нет канала с 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). Если JivoSite их получит, то отобразит оператору, если нет - то чат будет с Анонимусом. Значения могут быть обновлены в ходе чата.

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, желательно сразу нас уведомить.

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

JivoSite->Customer API: Agent Message

POST <Customer API HTTPS-endpoint URL>/JIVO_PUBLIC_ID
{
    "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 - идентификатор сообщения в JivoSite. Может использоваться в дальнейшем для уведомлений о доставке/прочтении.

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

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

{
“result” : “ok”
}

либо

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

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

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

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

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

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

Мультимедиа-сообщения передаются точно так же, как и текстовые сообщения, но имеют особый 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-запрос

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

Есть вопросы? Спросите техподдержку в чате на сайте, мы всегда рады помочь. Работаем 24 часа 7 дней в неделю.