Webhook API

Webhook API позволяет:

• получать события из VivoChat на ваш сервер;
• передавать информацию из вашей системы в VivoChat.

VivoChat отправляет HTTP POST-запросы на указанные URL.

Каждый webhook настраивается отдельно в интерфейсе VivoChat.

chat_accepted

chat_accepted позволяет:

• обновить информацию о клиенте в разделе «Контакты»;
• показать дополнительные данные в текущем диалоге.

chat_accepted отправляется, когда оператор принимает диалог в работу.

Как это работает

После принятия оператором диалога VivoChat отправляет HTTP POST-запрос на ваш сервер.

В запросе передаётся информация о диалоге, канале и userToken, если он был задан через setUserToken() (иначе null).

В ответе ваш сервер может вернуть:

• contactInfo — обновляет информацию о клиенте в разделе «Контакты»;
• customData — отображается в разделе «Дополнительно» в текущем диалоге.

В contactInfo можно передавать ограниченные данные о клиенте, используя:

• «name» — для имени клиента, string;
• «phone» — для телефона, string;
• «email» — «[email protected]».

В customData не ограничены типы передаваемых данных.

Настройка webhook

Webhook настраивается отдельно для каждого канала в интерфейсе VivoChat:

Управление → Каналы связи → [канал] → Интеграция Webhooks

Можно использовать один и тот же URL для нескольких каналов.

Формат запроса

{
  "type": "chat_accepted",
  "userToken": "USER_TOKEN",
  "chatId": "2c9c6f9e-2f47-4b85-9a59-3a59e2d87f9d", // Unique dialog identifier
  "channel": {
    "type": "widget",
    "id": "1CafijNcdgYtDhS3vg9b1V" // Unique channel identifier
  }
}

Поля запроса

Поле	Тип	Описание
type	string	Тип события. Всегда chat_accepted
userToken	string | null	Токен из setUserToken()
chatId	string	Идентификатор диалога
channel	object	Информация о канале

Пример ответа

{
    "result": "ok",
    "customData": [
        { "title": "Order", "content": "123456789" },
        { "title": "Tariff", "content": "Premium" }

    ],
    "contactInfo": {
        "name": "John Smith",
        "phone": "+14084987855",
        "email": "[email protected]"
    }
}

В этом примере:

• contactInfo обновляет данные клиента и отображает в разделе «Контакты»;
• customData отображает информацию о номере заказа и тарифном плане в разделе «Дополнительно» в текущем диалоге.

Поля ответа

Поле	Тип	Описание
result	string	Обязательное поле ответа
contactInfo	object	Обновляет информацию о клиенте
customData	array	Отображается только в текущем диалоге

Важно

• сервер должен отвечать HTTP-кодом 200;
• событие не повторяется автоматически при ошибке или таймауте;
• userToken будет null, если setUserToken() не использовался.

chat_finished

chat_finished вызывается после завершения диалога.

Используйте chat_finished, если необходимо:

• сохранить историю диалога в своей системе;
• анализировать обращения клиентов.

Как это работает

После завершения диалога VivoChat отправляет HTTP POST-запрос на ваш сервер.

Событие вызывается, если диалог:

• завершён;
• отклонён;
• заблокирован.

В запросе передаётся полная информация о завершённом диалоге:

• клиент;
• канал;
• текущий оператор;
• список операторов;
• сообщения;
• визиты;
• оценка диалога;
• интенты;
• время создания диалога;
• время завершения диалога.

Описание структуры post-запроса приведено в разделе «Структура данных chat_finished».

Настройка webhook

Webhook настраивается отдельно для каждого канала в интерфейсе VivoChat:

Управление → Каналы связи → [канал] → Интеграция Webhooks

Можно использовать один и тот же URL для нескольких каналов.

Формат ответа

Сервер должен ответить HTTP 200.

Минимальный успешный ответ:

{
  "result": "ok"
}

Поля ответа

Поле	Тип	Описание
result	string	Обязательное поле ответа

Важно

• сервер должен отвечать HTTP-кодом 200;
• событие не отправляется повторно при ошибке или таймауте;
• порядок получения события не гарантируется;
• рекомендуется игнорировать повторную обработку одного и того же chatId;
• часть полей может приходить как null.

Структура данных chat_finished

Событие chat_finished содержит полную информацию о завершённом диалоге.

Все поля типа timestamp передаются в формате Unix timestamp в секундах.

Пример post-запроса chat_finished

{
  "type": "chat_finished",
  "chatId": "2c9c6f9e-2f47-4b85-9a59-3a59e2d87f9d",
  "channel": {
    "id": "1CafijNcdgYtDhS3vg9b1V",
    "name": "Website Chat",
    "type": "widget"
  },
  "client": {
    "id": "4de4c8b4-2f5d-48e4-85d5-2fdf1a2b7c44",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+14084987855",
    "externalId": "customer_123"
  },
  "operator": {
    "id": "e11db1c1-fd5f-4d77-aed8-c0b4e5f8d4f1",
    "email": "[email protected]",
    "accepted": 1717420050
  },
  "operators": [
    {
      "id": "e11db1c1-fd5f-4d77-aed8-c0b4e5f8d4f1",
      "email": "[email protected]",
      "accepted": 1717420050
    }
  ],
  "messages": [
    {
      "type": "message",
      "sender": "client",
      "operatorId": null,
      "sent": 1717420060,
      "message": "Hello",
      "generated": false,
      "attachment": null
    },
    {
      "type": "message",
      "sender": "operator",
      "operatorId": "e11db1c1-fd5f-4d77-aed8-c0b4e5f8d4f1",
      "sent": 1717420080,
      "message": "How can I help you?",
      "generated": false,
      "attachment": null
    }
  ],
  "visits": [
    {
      "referer": "https://example.com/pricing",
      "city": "San Francisco",
      "country": "United States",
      "ipAddress": "203.0.113.10",
      "organization": "Example ISP"
    }
  ],
  "rate": {
    "satisfied": true,
    "comment": "Great support",
    "timestamp": 1717420300
  },
  "intents": [
    {
      "id": "9f0d4a8f-4f3e-4c9d-9c71-5d6e9d4f5a1b",
      "name": "support_request"
    }
  ],
  "created": 1717420000,
  "completed": 1717420300
}

Основные поля

Поле	Тип	Описание
type	string	Тип события. Всегда chat_finished
chatId	uuid	Идентификатор диалога
channel	Channel	Информация о канале
client	Client	Информация о клиенте
operator	Operator | null	Текущий оператор
operators	Operator[]	Список операторов диалога
messages	Message[] | MessageVoice[] | MessageCall[]	История сообщений
visits	Visit[]	Информация о визитах
rate	Rate | null	Оценка клиента
intents	Intent[]	Интенты диалога
created	timestamp	Время создания диалога
completed	timestamp | null	Время завершения диалога

Channel

Информация о канале, через который был создан диалог.

Поле	Тип	Описание
id	uuid	Идентификатор канала
name	string	Название канала
type	string	Тип канала: widget, email, telegram, whatsapp, instagram

Client

Информация о клиенте.

Поле	Тип	Описание
id	uuid	Идентификатор клиента в VivoChat
name	string	Имя клиента
email	string | null	Email клиента
phone	string | null	Телефон клиента
externalId	string | null	Идентификатор клиента в вашей системе
telegram	ClientTelegram | null	Telegram-аккаунт клиента
instagram	ClientInstagram | null	Instagram-аккаунт клиента

ClientTelegram

Telegram-аккаунт клиента.

Поле	Тип	Описание
id	string	ID пользователя в Telegram
chatId	string	ID чата в Telegram
username	string | null	Username клиента
firstName	string | null	Имя клиента
lastName	string | null	Фамилия клиента

ClientInstagram

Instagram-аккаунт клиента.

Поле	Тип	Описание
id	string	ID аккаунта
username	string | null	Username клиента

Operator

Информация об операторе.

Поле	Тип	Описание
id	uuid	Идентификатор оператора
email	string	Email оператора
accepted	timestamp	Время принятия диалога

Messages

Массив messages[] может содержать разные типы сообщений.

Тип	Описание
message	Текстовое сообщение
voice	Голосовое сообщение
call	Запись звонка

Message

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

Поле	Тип	Описание
type	string	Всегда message
sender	string	client или operator
operatorId	uuid | null	Идентификатор оператора
sent	timestamp	Время отправки
message	string	Текст сообщения
generated	boolean	Сообщение сгенерировано AI
attachment	Image | Document | Video | null	Вложение

MessageVoice

Голосовое сообщение.

Поле	Тип	Описание
type	string	Всегда voice
voice	Voice	Аудиозапись
sender	string	client или operator
operatorId	uuid | null	Идентификатор оператора
sent	timestamp	Время отправки

Voice

Аудиозапись голосового сообщения.

Поле	Тип	Описание
length	int	Длительность записи
url	string	URL аудиофайла

MessageCall

Запись звонка.

Поле	Тип	Описание
type	string	Всегда call
call	Call	Запись звонка
sender	string	Всегда operator
operatorId	uuid | null	Идентификатор оператора
sent	timestamp	Время звонка

Call

Запись телефонного звонка.

Поле	Тип	Описание
size	int	Размер файла
url	string	URL аудиофайла
result	string	Результат звонка

Attachment

Поле attachment может содержать изображение, документ или видео.

Image

Поле	Тип	Описание
type	string	Всегда image
url	string	URL изображения
originalFileName	string	Имя файла
height	int	Высота изображения
width	int	Ширина изображения

Document

Поле	Тип	Описание
type	string	Всегда document
url	string	URL документа
originalFileName	string	Имя файла

Video

Поле	Тип	Описание
type	string	Всегда video
url	string	URL видео
originalFileName	string	Имя файла
length	int	Длительность видео

Visit

Информация о визите клиента.

Поле	Тип	Описание
referer	string | null	URL страницы
city	string	Город клиента
country	string	Страна клиента
ipAddress	string	IP-адрес
organization	string | null	Провайдер или организация

Rate

Оценка диалога клиентом.

Поле	Тип	Описание
satisfied	boolean	Положительная или отрицательная оценка
comment	string | null	Комментарий клиента
timestamp	timestamp	Время оценки

Intent

Интент диалога.

Поле	Тип	Описание
id	uuid	Идентификатор интента
name	string	Название интента

client_check_token

Событие client_check_token используется для верификации авторизованного клиента.

Используйте client_check_token, если необходимо:

• связать диалог с клиентом из вашей системы;
• показывать оператору имя, телефон и email клиента;
• объединять историю диалогов клиента между устройствами и сессиями.

Как это работает

Если на сайте используется авторизация, передайте токен пользователя через setUserToken().

При первом открытии чата VivoChat отправит HTTP POST-запрос с типом client_check_token на URL верификации клиента.

В запросе передаётся:

• тип события;
• userToken, переданный через setUserToken().

Ваш сервер должен:

• проверить токен;
• найти клиента в вашей системе;
• вернуть clientId;
• при необходимости вернуть контактные данные клиента.

Если клиент найден:

• VivoChat свяжет диалог с клиентом;
• оператор увидит контакты клиента в разделе «Контакты»;
• история диалогов будет объединяться между сессиями.

Если клиент не найден:

• верните успешный ответ без clientId;
• диалог продолжится как анонимный.

Кэширование

Ответ верификации кэшируется на стороне VivoChat.

Повторное открытие чата с тем же userToken не вызывает повторный запрос на ваш сервер.

Для повторной верификации необходимо передать новый токен.

Настройка URL верификации

URL верификации настраивается один раз для всей организации:

Настройки → Диалоги → Адрес верификации клиента

URL используется для всех каналов организации.

Формат запроса

{
  "type": "client_check_token",
  "userToken": "USER_TOKEN"
}

Поля запроса

Поле	Тип	Описание
type	string	Тип события. Всегда client_check_token
userToken	string	Токен из setUserToken()

Формат ответа

{
    "result": "ok",
    "clientId": "customer_123",
    "contactInfo": {
        "name": "John Smith",
        "phone": "+14084987855",
        "email": "[email protected]"
    }
}

Поля ответа

Поле	Тип	Описание
result	string	Обязательное поле ответа
clientId	string | null	Постоянный идентификатор клиента в вашей системе
contactInfo	object	Контактные данные клиента

ContactInfo

Все поля объекта contactInfo опциональны.

Поле	Тип	Описание
name	string | null	Имя клиента
phone	string | null	Телефон клиента
email	string | null	Email клиента

Важно

• сервер должен отвечать HTTP-кодом 200;
• запрос не отправляется повторно при ошибке или таймауте;
• userToken передаётся без проверки и валидации со стороны VivoChat;
• формат токена определяется вашей системой;
• если clientId отсутствует, клиент считается анонимным;
• при выходе пользователя из аккаунта рекомендуется очищать токен vivo_api.setUserToken(null), чтобы другие пользователи браузера не имели доступа к переписке;
• подробное описание работы верификации клиентов описано в соответствующем разделе «Верификация клиентов».

ticket_create

ticket_create отправляется при создании тикета.

Используйте ticket_create, если необходимо:

• уведомить внешнюю систему о новом тикете;
• запускать автоматизации после создания тикета на стороне вашего сайта или продукта.

Для настройки и получения документации обратитесь в команду разработки VivoChat.

ticket_finished

ticket_finished отправляется при завершении тикета.

Используйте ticket_finished, если необходимо:

• уведомить внешнюю систему о закрытии тикета;
• запускать автоматизации после закрытия тикета на стороне вашего сайта или продукта.

Для настройки и получения документации обратитесь в команду разработки VivoChat.