Инструкция по настройке Omni-интеграции для Zoho CRM

В классических сценариях интеграции порядок работы с CRM заранее определен: пока ваш процесс вписывается в него, всё работает. Omni-интеграция нужна там, где у вас есть что-то своё: собственное поле, собственное условие, собственная цепочка действий.

Это гибкий способ подключения CRM к UniTalk, где логику обмена данными вы настраиваете сами: какие сущности задействованы — включая пользовательские, по каким правилам искать клиента, какие поля заполнять, к каким событиям привязывать действия. Если CRM умеет отправлять веб-хуки, работает и обратное направление: событие в CRM запускает действие в UniTalk.

На практике это выглядит просто: в карточке клиента появляется кнопка «Связаться», а телефоны, email и чаты подтягиваются в Web Dialer без ручного копирования.

Гибкость означает, что интеграция будет делать именно то, что вы зададите, — поэтому настраивать её следует последовательно, шаг за шагом. Именно так построена эта инструкция.

Теперь, когда наше приложение установлено в ZohoCRM, можно приступить к подключению и настройке Omni-интеграции

Для подключения Omni-интеграции перейдите в личный кабинет в раздел «API и автоматизация» → «Omni-интеграции».

Также вы можете открыть страницу по ссылке:
https://my.unitalk.cloud/api-automation/omni-integrations

И нажмите на «Подключить» возле нужной Вам интеграции

В этой инструкции рассмотрим детально вариант подключение Omni-интеграции с CRM-системой ZohoCRM

1. Подключение

Для авторизации в СРМ нажмите кнопку «Подключить»

Первая вкладка после раздела «Настройки подключения» — «Сущности интеграции».

На этой вкладке необходимо выбрать сущности CRM-системы, с которыми будет работать Omni-интеграция и сохранить настройки. Для выбраных сущностей интеграция сможет выполнять поиск, создание и обновление записей в процессе работы.

Доступные сущности для ZohoCRM

Omni-интеграция поддерживает работу со стандартными сущностями ZohoCRM:

• Вендоры
• Встреча
• Задача
• Заказанные позиции
• Заказы на покупку
• Заказы на продажу
• Звонок
• Кампания
• Коммерческие предложения
• Контакт
• Контрагент
• Лид
• Обращения
• Позиции в ценовом предложении
• Позиции покупки
• Позиции, за которые выставлен счет
• Прайс-листы
• Продукты
• Решения
• Сделка
• Счета

На этой вкладке вы найдёте базовые параметры управления системой. Она содержит:

• Общие настройки интеграции: активация и главные правила взаимодействия систем.
• Общие настройки сущностей интеграции: логика поведения создаваемых или обновляемых элементов CRM.
• Расположение операторов: привязка и соответствие менеджеров между кабинетом UniTalk и CRM.

Визуализация звонков в CRM

Функция «Показывать стандратный виджет CRM при входящих/исходящих звонках»: Если API вашей CRM-системы позволяет выводить стандартное всплывающее окно (попап) во время звонков и этот чекбокс включен, система будет автоматически показывать его оператору.

Дополнительные настройки отображения в SIP-клиенте

• Чекбокс «Отображать ответственного при входящих звонках в SIP-клиенте»: Эта функция работает аналогично настройке с таким же названием в наших старых интеграциях. Если её включить, оператор при входящем звонке будет видеть в SIP-клиенте имя менеджера, который закреплен за этим клиентом в CRM.
• Настройка «Приоритет сущностей для липучки и ответственного в SIP-клиенте»: Клик по этой кнопке добавляет поле выбора (селект). В нем вы можете выбрать одну из сущностей вашей интеграции, которые вы включили ранее на 2-й вкладке.

Для каждой отдельной сущности, которую вы активировали на вкладке «Сущности интеграции», система автоматически создаст отдельный блок управления. Эти блоки будут отображаться в формате: «Сущность — название_сущности» (например: Сущность — Звонок, Сущность — Лид и т.д.). Внутри каждого такого блока вы сможете детально настроить логику работы именно с этим типом данных.

История звонков и синхронизация с сущностями

Ссылки для быстрого поиска сущностей будут полностью отсутствовать в интерфейсе в двух случаях:

• Если ваша интеграция с CRM сейчас полностью выключена.
• Если конкретная сущность (например, лид или компания) не была активирована вами ранее на 2-й вкладке настроек

Настройки и возможности Web Dialer

В разделе настроек каждой сущности вам доступны два важных параметра для работы с Web Dialer:

• Чекбоксы «Отправлять в Web Dialer при входящих/исходящих звонках»: Если функция включена, то во время звонков непосредственно в Web Dialer будет отображаться название найденной сущности, имя ответственного менеджера и прямая ссылка на эту сущность в CRM.
• Чекбокс «Показывать кнопку Связаться в CRM»: Если активировать эту галку, то при использовании Web Dialer на странице конкретной сущности в CRM появится кнопка «Связаться».

Суть функционала: При клике на кнопку «Связаться» система автоматически собирает всю доступную информацию о клиенте (телефоны, email, ID существующего чата или данные для старта нового) и передает её в дайлер. Это позволяет оператору мгновенно позвонить или написать клиенту прямо из интерфейса Web Dialer.

Это современная замена обычному звонку по клику из CRM, которая работает стабильно, не требует разработки сложных и дорогих индивидуальных CRM-виджетов, а также позволяет писать в чаты, SMS и Viber непосредственно через веб-дайлер

Правила поиска сущностей по умолчанию для звонков/чатов

Эти настройки позволяют задать правила поиска сущностей по умолчанию отдельно для чатов и отдельно для звонков.

Система автоматически использует эти правила в следующих случаях:

• При поиске динамического значения обработки событий. Если сущность не была найдена по правилам, указанным в профилях действий, система выполнит поиск по правилам, заданным по умолчанию. Для событий чатов будут использоваться правила для чатов, для всех остальных событий — правила для звонков.
• Для отображения информации в SIP-клиенте. Чтобы показать оператору название найденной сущности и ответственного менеджера, система всегда использует правила поиска по умолчанию для звонков.
• При настройке функционала «липучка» во входящих сценариях звонков. Правила поиска по умолчанию автоматически подставляются как базовые настройки.
• При создании новых или еще не настроенных действий. Для событий чатов автоматически используются правила для чатов, а во всех остальных случаях — правила для звонков.

Отметьте чекбоксами те поля, которые вам нужны в динамических значениях обработки событий.

Работа с полями CRM и выбор динамических значений

В сущностях CRM обычно присутствует очень много дополнительных или устаревших полей, которые не используются в работе телефонии. Чтобы система работала быстро и стабильно, при получении данных через API мы не вычитываем абсолютно все поля подряд.

Поля, на которые уже завязана внутренняя логика интеграции, система всегда забирает автоматически — в списке выбора вы их не увидите.

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

Какие поля доступны по умолчанию (без проставления галочек):

• ID сущности
• Время создания сущности
• Время последнего обновления сущности
• Ответственный за сущность
• Основные текстовые поля: имя, фамилия, отчество, название, тема (обычно доступны по умолчанию, но могут быть исключения в зависимости от CRM)
• Основной телефон
• Основной email
• «Все телефоны» — это наше системное псевдополе (создается автоматически в коде UniTalk), куда собираются и записываются номера абсолютно из всех телефонных полей сущности.
• «Все email» — аналогичное псевдополе, куда собираются электронные адреса из всех полей сущности.
• Воронка
• Ссылка на другую сущность — поле, значением которого является ID связанного элемента (например, связь сделки с контактом). Обычно оно называется в соответствии с сущностью: «Контакт», «Сделка» и т. д.
• Все поля, имеющие тип данных «телефон»
• Все поля, имеющие тип данных «email»
• Все поля, которые являются обязательными для заполнения при создании сущности в CRM.

3.2. Раздел Расположение операторов

Дает возможность задать привязку между пользователями CRM, пользователями UniTalk, SIP линиями и мобильными номерами операторов

Настройка расположения операторов

В этом разделе вы настраиваете связь между менеджерами в вашей CRM и пользователями в системе UniTalk. Настройка выполнена в виде таблицы, где каждая колонка отвечает за конкретные данные:

• 1 колонка (Имя пользователя в CRM): Здесь отображается или выбирается конкретный менеджер из вашей CRM-системы.
• 2 колонка (Пользователи UniTalk): Здесь в выпадающем списке выбирается соответствующий пользователь UniTalk. Одного и того же пользователя UniTalk можно указать в таблице не более одного раза. Ограничение: Мультиселект, где можно выбрать сразу нескольких пользователей UniTalk, которые соответствуют этому менеджеру.
• 3 колонка (SIP-линии): Тут также в выпадающем списке выбирается конкретная SIP-линия которая будет закреплена за этим пользователем. Одну и ту же SIP-линию можно добавить в таблице не более одного раза. Ограничение: Мультиселект для выбора SIP-линий. Вы можете закрепить за менеджером сразу несколько линий.
• 4 колонка (Мобильные номера): Поле (инпут) для ввода мобильных номеров телефонов операторов. Если номеров несколько, указывайте их через запятую. Ограничение: Номера должны быть валидными GSM-номерами. Один и тот же номер телефону можно указать в таблице не более одного раза.

Профили действий — это место автоматизации в Omni-интеграциях. Они определяют: как именно система ищет сущности в CRM, что она делает с ними после поиска, по каким правилам заполняются поля и как распределяется график ответственных менеджеров по умолчанию.

Управление профилями действий происходит на трех последующих вкладках:

1. Интеграция звонки
2. Интеграция чаты
3. Интеграция обработка событий

4.1. Вкладки «Звонки» и «Чаты» (Стандартные события)

Здесь вы задаете профили действий для базовых системных событий.

• Для чатов доступны события:

1. Начало чата
2. Завершение чата
3. Обновление полей чата 

• Для звонков доступны события: 

1. Входящий звонок — начало
2. Входящий звонок — ответ
3. Входящий звонок — завершение
4. Исходящий звонок — начало
5. Исходящий звонок — ответ
6. Исходящий звонок — завершение
7. Запланирован C2C (Click-to-Call) 

Ключевые отличия логики обработки звонков по сравнению со старыми интеграциями

Click-to-Call (C2C).
В старых интеграциях при запланированном C2C-звонке сущности создавались автоматически, а к ним добавлялся стандартный комментарий. В Omni-интеграциях такая автоматизация отсутствует: теперь вы можете самостоятельно настроить сценарий обработки звонка и определить, какие действия должны выполняться.

Разделение событий.
Ранее все шесть событий звонка обрабатывались в рамках одного общего алгоритма. Создание сущностей для исходящих звонков управлялось одной общей настройкой, а сам алгоритм выполнялся только один раз за звонок: в момент ответа, либо, если ответа не было, после завершения звонка.

Гибкость настройки.
В новой интеграции каждое событие звонка настраивается независимо. При необходимости можно создать сущности для каждого события (до двух раз для входящего звонка и до трёх раз для исходящего). Однако мы рекомендуем использовать такую возможность осознанно, чтобы избежать дублирования данных, избыточных сущностей и возможных ошибок в CRM.

Чтобы система работала стабильно , настраивайте профили действий следующим образом:

• Для событий ответа на звонок добавьте условие, чтобы профиль выполнялся только в том случае, если на звонок ответили.
• Для событий завершения звонка добавьте условие, чтобы профиль выполнялся только в том случае, если на звонок не ответили.

4.2. Вкладка «Интеграция: обработка событий»

Эта вкладка предназначена для создания собственных сценариев автоматизации. Нажав кнопку «Добавить», вы можете создать любое количество профилей действий, присвоив каждому понятное и удобное название.

Доступные динамические значения на вкладках

Набор доступных динамических значений зависит от вкладки и типа события.

Вкладка «Обработка событий»

На этой вкладке доступны практически все динамические значения системы, за исключением:

• блока «Omni-интеграция — данные авторизации»;
• устаревших значений категории «CRM».

Вкладка «Чаты»

Для сценариев обработки чатов доступны следующие группы динамических значений:

• Разное;
• Чат;
• Аналитика (стандартная);
• Omni-интеграция;
• Контактная книга Unitalk;
• В истории звонков существует звонок;
• Данные о первом звонке;
• Данные о последнем звонке.

Вкладка «Звонки»

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

Событие заказа Click-to-Call (C2C)

Доступны группы:

• Разное;
• Click to call;
• Аналитика;
• Omni-интеграция;
• Контактная книга Unitalk;
• В истории звонков существует звонок;
• Данные о первом звонке;
• Данные о последнем звонке.

События исходящих звонков

Доступны группы:

• Разное;
• Звонок;
• Omni-интеграция;
• Контактная книга Unitalk;
• В истории звонков существует звонок;
• Данные о первом звонке;
• Данные о последнем звонке.

События входящих звонков

Доступен наиболее полный набор динамических значений, включающий:

• Разное;
• Звонок;
• Click to call;
• Аналитика;
• Omni-интеграция;
• Голосовое меню;
• Обзвон;
• Данные номера обзвона;
• Голосовой робот;
• Контактная книга Unitalk;
• В истории звонков существует звонок;
• Данные о первом звонке;
• Данные о последнем звонке.

4.3. Статусы и отображение профилей действий

Отображение профилей действий и их статусов зависит от выбранной вкладки.

Вкладки «Звонки» и «Чаты»

На этих вкладках всегда отображается полный список стандартных событий. Название каждого профиля совпадает с названием соответствующего события, например «Входящий звонок — ответ».

Рядом с названием профиля отображается один из трех статусов:

• Не настроено — для данного профиля еще не задана логика обработки событий.
• ON — профиль настроен, включен и выполняет все заданные действия.
• OFF — профиль настроен, но временно отключен. Пока профиль находится в этом состоянии, действия, связанные с данным событием, выполняться не будут.

Вкладка «Обработка событий»

На этой вкладке создаются пользовательские (кастомные) профили автоматизации, поэтому принцип отображения отличается.

• Вместо названия системного события отображается имя профиля, которое было указано при его создании.
• Для таких профилей доступны только два статуса:
  • ON — профиль активен и выполняет настроенную логику.
  • OFF — профиль отключен и временно не выполняется.

Статус «Не настроено» для пользовательских профилей отсутствует, поскольку каждый профиль создается вручную и изначально предназначен для реализации определенного сценария автоматизации.

5. Импорт сущностей

Данный раздел используется для импорта сущностей из CRM, фильтруя часть из них по условиям полей сущностей и выполнить обработчик событий на те поля, которые подошли по условиям

Импорт сущностей из CRM
Импорт предназначен для автоматического поиска сущностей в CRM и передачи их в обработчики событий по заданным правилам.

Общие настройки
Название профиля импорта.

Автозапуск
Включает автоматический запуск импорта в соответствии с выбранным расписанием.
Настройка становится доступной только после сохранения профиля импорта.

Когда запускать импорт
Определяет расписание автоматического запуска. Доступны два режима.

• Ежедневно в указанное время
  Импорт будет запускаться один раз в день в выбранное время. Такой режим удобно использовать, например, для ежедневной передачи новых номеров в кампанию обзвона.
• Через заданный интервал
  Импорт запускается с указанной периодичностью (в минутах). Отсчет начинается с момента завершения предыдущего запуска данного профиля.

Например:

• сделки из воронок 1 и 2 автоматически передаются в кампанию обзвона №1;
• сделки из воронки 3 — в кампанию обзвона №2.

Важно. Одновременно может выполняться только один профиль импорта. Если в момент запланированного запуска уже работает другой импорт, новый запуск будет ожидать своей очереди. Поэтому при запуске по интервалу фактическое время выполнения может отличаться от заданного (например, вместо 15 минут импорт может начаться через 20–25 минут).

Настройки поиска

Искать по полю с временем

Поле CRM, по которому выполняется поиск сущностей.

Для выбора доступны только поля типа «Дата и время».

Время от / Время до

Диапазон времени, в пределах которого будут искаться сущности.

Можно указать:

• только начало периода;
• только конец периода;
• обе границы одновременно.

Поддерживаются как точные дата и время, так и относительные значения, например:

• за последние 30 минут;
• за последние 24 часа;
• за последние 7 дней.

Настройки обработки

Обработчики событий

Позволяет выбрать до 10 обработчиков событий, которые будут последовательно выполняться для каждой найденной сущности.

Найти связанные сущности перед выполнением действий

Перед запуском обработчиков система дополнительно загружает связанные сущности.

Например, при обработке сделки автоматически будет получен связанный контакт, что позволит использовать его номер телефона или другие данные в обработчиках.

Сохранить время обработки сущности в поле

Записывает в выбранное поле текущие дату и время передачи сущности в обработку.

Фиксируется именно момент постановки сущности в очередь на обработку, а не завершение выполнения обработчиков.

Повторно обработать сущность, если прошло больше чем N дней

Позволяет повторно запускать обработку уже обработанных сущностей.

Если с момента предыдущей обработки прошло больше указанного количества дней, сущность будет обработана повторно. В противном случае она будет пропущена.

Настройки API

Пауза между запросами к API CRM (сек)

Задает задержку между последовательными запросами к API CRM.

Обязательный параметр.

Допустимые значения: от 1 до 15 секунд.

Исключения

Ничего не делать, если выполняются условия

Позволяет задать условия, при выполнении которых найденная сущность будет пропущена и не попадет в обработку.

Это удобно, если необходимо исключить определенные категории записей из автоматической обработки.

Ручной запуск

После сохранения профиля становится доступна кнопка «Начать импорт», позволяющая запустить импорт вручную в любой момент.

Принцип работы импорта

После запуска импорт выполняет следующие действия:

1. Выполняет поиск сущностей в CRM по выбранному полю типа «Дата и время» с учетом заданного диапазона.
2. Загружает найденные сущности пакетами по 50 записей за один запрос API.
3. Последовательно помещает каждую найденную сущность в очередь обработки.
4. Проверяет поле «Время обработки»:
   • если поле пустое — сущность передается в обработку;
   • если поле заполнено и повторная обработка не настроена — сущность пропускается;
   • если настроена повторная обработка, но с предыдущей обработки прошло меньше указанного количества дней — сущность также пропускается;
   • если прошло больше указанного периода — сущность будет обработана повторно.
5. Проверяет условия из блока «Ничего не делать, если выполняются условия». При совпадении хотя бы одного условия дальнейшая обработка прекращается.
6. При включенной опции «Найти связанные сущности перед выполнением действий» дополнительно загружает связанные записи (например, контакт, связанный со сделкой).
7. Записывает текущее время в поле «Время обработки».
8. Последовательно выполняет все выбранные обработчики событий.

Такой механизм позволяет безопасно автоматизировать обработку данных CRM, исключать повторную обработку записей, контролировать нагрузку на API и гибко настраивать сценарии автоматизации.

6. Входящие вебхуки

Настройка выполняется отдельно для каждой сущности, выбранной в разделе «Сущности интеграции». Для каждой сущности можно создать собственный профиль обработки и назначить один или несколько обработчиков событий, которые будут запускаться при поступлении вебхука.

Принцип работы

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

В старых интеграциях CRM передавала в вебхуке номер телефона. Система находила соответствующий контакт или лид по этому номеру и, в зависимости от настроенного сценария, выполняла необходимое действие — например, добавляла номер в кампанию обзвона или удаляла его из нее.

В новом механизме каждый вебхук привязан к конкретной сущности CRM. Поэтому вместо номера телефона CRM должна передавать идентификатор (ID) сущности, для которой был вызван вебхук.

Например:

• если вебхук настроен для сделок, необходимо передавать ID сделки;
• если вебхук настроен для контактов, необходимо передавать ID контакта;
• если вебхук настроен для лидов, необходимо передавать ID лида.

После получения запроса система выполняет поиск сущности по переданному идентификатору. При необходимости она также может загрузить связанные сущности (например, контакт, связанный со сделкой) и использовать их данные при выполнении обработчиков событий.

6.1. Требования к вебхуку

Вебхук может быть отправлен одним из двух HTTP-методов:

• GET;
• POST.

Запрос обязательно должен содержать идентификатор сущности, который может передаваться одним из следующих способов:

• в параметрах URL;
• в теле запроса в формате JSON;
• в теле запроса в формате form-data;
• в теле запроса в формате application/x-www-form-urlencoded.

Идентификатор должен быть передан в параметре с именем:

• id;
• entityId.

Регистр символов не учитывается, поэтому следующие варианты являются равнозначными:

• id
• ID
• Id
• entityId
• EntityId
• ENTITYID

Если CRM не позволяет использовать указанные названия параметров, при необходимости может быть реализована поддержка дополнительных имен.

6.2. Создание профиля обработки

Для создания нового профиля необходимо нажать кнопку «+» в карточке соответствующей сущности.

После создания профиля необходимо:

1. Выбрать один или несколько обработчиков событий.
2. Сохранить настройки.

При поступлении вебхука для данной сущности будут последовательно выполнены все выбранные обработчики.

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

Чтобы профиль обработчика начал работать, его нужно дополнительно включить с помощью переключателя; там же его можно отключить. Включен ли профиль или нет, можно увидеть сразу справа от названия профиля входного веб-хука.

Создание правила

1. Нажмите кнопку Create Rule (Создать правило).

1. В поле Module (Модуль) выберите тип сущности. Он обязательно должен совпадать с типом сущности, URL которой будет использоваться во входящем вебхуке на стороне UniTalk.
   Например, если в личном кабинете UniTalk профиль создан для сущности Leads, то в Zoho CRM также необходимо выбрать модуль Leads.
2. В поле Rule Name укажите произвольное название правила. Рекомендуется использовать понятное имя, которое позволит легко определить назначение правила в дальнейшем.

8. В окне настройки параметров вебхука:
   • Укажите название для данного действия.
   • Выберите HTTP-метод: GET или POST.
   • Вставьте ранее скопированный URL вебхука.
9. Затем настройте передачу идентификатора клиента одним из двух способов.

Способ 1. Передача через параметр запроса

• Добавьте параметр id.
• В качестве значения параметра выберите идентификатор сущности из выпадающего списка (через символ #), например Lead Id или Deal Id.

Способ 2. Передача данных в теле запроса (для метода POST)

Если вы выбрали метод POST, вы также можете настроить Request Body следующим образом:

• Переключите режим на User-defined.
• Выберите формат данных JSON.
• Самостоятельно сформируйте список полей, которые будут передаваться в UniTalk.

С помощью символа # вы можете добавить в тело запроса любые динамические поля CRM-карточки, например:

• номер телефона;
• адрес электронной почты (Email);
• ответственного менеджера;
• UTM-метки;
• и другие поля сущности.

Это позволит UniTalk мгновенно получить полный контекст по лиду или сделке и выполнить необходимый сценарий обработки данных.