Astrum Agency

Документация

Документация: Jivo интеграция

Обзор

Приложение «Jivo интеграция» связывает чаты Jivo с CRM Битрикс24. Оно создаёт и обновляет лиды или сделки в Битрикс24 при событиях из Jivo (принятие чата, обновление, завершение, офлайн-сообщения) и позволяет просматривать список чатов и настраивать источники Jivo в интерфейсе приложения.

Основные возможности

  • Вебхук Jivo — приложение принимает события от Jivo и создаёт или обновляет сущности CRM (лид или сделка).
  • Гибкие настройки по каналу — для каждого виджета Jivo можно задать тип сущности (лид/сделка), ответственного, источник, момент создания лида и способ выбора ответственного.
  • Список чатов — на главной вкладке отображаются чаты Jivo с поиском, фильтром по статусу и пагинацией; для каждого чата показывается ссылка на лид/сделку в Битрикс24.
  • Внешний API — получение списка лидов и статистики по лидам по API-ключу (для интеграций и отчётов).

Интерфейс приложения

После установки приложения открывается интерфейс с двумя вкладками: Главная и Настройки.

Вкладка «Главная»

  • Список чатов Jivo — таблица чатов с колонками:
  • Чат / CRM — идентификатор чата и ссылка на лид или сделку в Битрикс24 (если создана).
  • Начат — дата и время начала чата.
  • Клиент — имя посетителя.
  • Контакты — телефон и email.
  • Сообщение — начало первого сообщения.
  • Статус — «В ожидании», «Завершён», «Ошибка».
  • Поиск — по имени, телефону, email или тексту первого сообщения.
  • Фильтр по статусу — все / в ожидании / завершён / ошибка.
  • Пагинация — переключение страниц и отображение диапазона записей.

Вкладка «Настройки»

  • URL вебхука Jivo — отображается и копируется одной кнопкой. Этот URL нужно указать в настройках канала (виджета) в Jivo в разделе вебхуков. (Управление -> Управление каналами -> Нажмите "Настроить" на целевом канале -> Настройки интеграции для разработчиков -> Включить Webhooks (Вкл) -> Вставьте URL из приложения в поле "URL для Webhooks")
  • Источники Jivo — таблица подключённых виджетов. Для каждого источника можно указать:
  • Widget ID — идентификатор виджета из Jivo (последовательность букв и цифр, можно найти в настройках канала в разделе "Установка" - будет расположен в коде встройки на сайт, например U4LbHtO49C).
  • Название — произвольное имя для удобства.
  • Сущность CRM — лид или сделка.
  • Ответственный — сотрудник Битрикс24 по умолчанию и способ его выбора (см. ниже).
  • Источник — источник из справочника Битрикс24.

Настройка источника Jivo (виджета)

В модальном окне «Добавление источника» / «Редактирование источника» задаются параметры.

Обязательные поля

  • ID виджета — идентификатор виджета из личного кабинета Jivo (например, в настройках канала или в URL виджета). Должен совпадать с widget_id в запросах вебхука.

Дополнительные поля

  • Название — любое имя для отображения в таблице источников.

Сущность CRM

  • Лид — в Битрикс24 создаются и обновляются лиды.
  • Сделка — создаются и обновляются сделки.

Ответственный

  • Ответственный по умолчанию — сотрудник Битрикс24 из выпадающего списка (подгружается с портала). Используется, если выбран способ «По умолчанию».
  • Как выбирать ответственного:
  • По умолчанию — всегда использовать выбранного «Ответственного по умолчанию».
  • По Jivo ID — искать сотрудника в Битрикс24 по полю пользователя UF_ASTRUM_JIVO_ID, равному ID оператора Jivo (из вебхука). Если приложение ещё не создавало это поле — оно будет создано при первом обращении к API пользователей.
  • По email — искать сотрудника по email оператора Jivo.

Когда создавать лид в Битрикс24

  • При начале чата — лид/сделка создаётся при событии «чат принят» (chat_accepted) или при офлайн-сообщении (offline_message). При завершении чата сущность обновляется.
  • При завершении чата — лид/сделка создаётся при событии «чат завершён» (chat_finished) или при офлайн-сообщении. До завершения в CRM ничего не создаётся.

Источник

  • Источник — элемент справочника источников Битрикс24 (CRM). Подставляется в поле «Источник» при создании/обновлении лида или сделки.

После сохранения источник появляется в таблице. Убедитесь, что в Jivo в настройках канала указан тот же Widget ID и прописан URL вебхука приложения.

Настройка вебхука в Jivo

  1. Войдите в личный кабинет Jivo и откройте настройки нужного канала (виджета).
  2. Найдите раздел Управление.
  3. Выберите нужный канал и нажмите кнопку Настроить.
  4. Перейдите в раздел Настройки интеграции для разработчиков.
  5. Включите отправку событий на вебхук в поле Включить Webhooks.
  6. Укажите URL для Webhooks из вкладки «Настройки» приложения (кнопка «Копировать»).

Формат и описание событий: документация Jivo Webhooks.

Приложение отвечает на POST-запросы с телом в формате JSON. Ответ всегда в формате JSON с полем result (ok или error).

Что попадает в лид/сделку Битрикс24

При создании или обновлении лида/сделки приложение заполняет стандартные поля CRM данными из Jivo (имя, телефон, email посетителя и т.п.), а также:

  • Комментарий — в комментарий добавляются текст переписки (если Jivo присылает сообщения в вебхуке) и ссылка на архив чата в Jivo в формате: https://app.jivosite.com/chat/archive/{chat_id}_chat-{widget_id}-{chat_id}

Таким образом, в карточке лида/сделки видна переписка и можно перейти в чат в Jivo.

События Jivo и поведение приложения

| Событие | Поведение | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | chat_accepted | Если стратегия «При начале чата» — создаётся лид/сделка, сохраняется привязка чат ↔ CRM. Если «При завершении чата» — только запоминается чат, сущность не создаётся. | | chat_updated | Если лид/сделка уже создана (стратегия «При начале чата») — обновляются поля и комментарий. | | chat_finished | Если стратегия «При завершении чата» и лид/сделка ещё не создана — создаётся в этот момент. Если сущность уже была — обновляется и помечается как завершённая. | | offline_message | Всегда создаётся или обновляется лид/сделка (офлайн-обращения всегда попадают в CRM). Момент создания зависит от стратегии «При начале чата» / «При завершении чата». |

Статусы синхронизации в приложении: «В ожидании», «Завершён», «Ошибка» — отображаются в списке чатов на главной вкладке.

Частые вопросы и проблемы

Вебхук не срабатывает / лид не создаётся

  • Проверьте, что в Jivo указан точный URL из приложения (с протоколом и путём).
  • Убедитесь, что Widget ID в настройках канала Jivo совпадает с «ID виджета» в источнике в приложении.
  • Убедитесь, что в Jivo включена отправка нужных событий (chat_accepted, chat_finished, offline_message и при необходимости chat_updated).

Ответственный не подставляется (стратегия «По Jivo ID»)

  • В Битрикс24 у сотрудников должно быть заполнено пользовательское поле UF_ASTRUM_JIVO_ID значением, равным ID агента в Jivo (из вебхука). Приложение создаёт это поле при обращении к API пользователей, если его ещё нет.

В списке чатов нет записей

  • Список заполняется после того, как произошли события (чат принят, офлайн-сообщение и т.д.) и приложение их обработало. Проверьте, что вебхук настроен и виджет добавлен в «Настройках».

Ошибка при вызове API (leads / leads/statistics)

  • Проверьте, что передаёте правильный API-ключ (часть URL после /webhook/jivo/).
  • Убедитесь, что запрос идёт на тот же домен, где установлено приложение, и путь начинается с /api/v1/.

Ссылка на чат в Jivo в комментарии лида

Формат ссылки:
https://app.jivosite.com/chat/archive/{chat_id}_chat-{widget_id}-{chat_id}

Если ссылка не открывается — проверьте, что chat_id и widget_id в вебхуках Jivo соответствуют реальным значениям в вашем кабинете Jivo.

Поддержка

При возникновении проблем обращайтесь в службу поддержки приложения (если в интерфейсе указана ссылка «Поддержка») или к администратору портала Битрикс24.