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

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

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

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

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

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

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

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

Где взять необходимые данные, сейчас детально разберём.

1. В CRM системе перейдите  в раздел «Настройки/Коммуникации/Телефония» и нажмите “Добавить новую службу».

2. Далее в открытом окне необходимо:

• Указать «Название» канала в произвольной форме.
• В пункте «Сервис телефонии» выбрать Other.
• В пункте «Ссылка для инициализации звонка» вставить ссылку:

https://api.unitalk.cloud/tracking/crmConnector/directCall/KEYCRM?type=initialize

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

В этой панели важно, что бы «статус» был активным для работы интеграции.

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

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

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

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

• Заказ
• Компания
• Лид
• Покупатель

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

• Общие настройки интеграции: активация и главные правила взаимодействия систем.
• Общие настройки сущностей интеграции: логика поведения создаваемых или обновляемых элементов 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.

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

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

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

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

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

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

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

Вкладка «Звонки»: Здесь фильтрация полей работает точнее всего под каждое событие:

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

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

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

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

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

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

Поскольку на этой вкладке вы создаете собственные, кастомные сценарии автоматизации, логика отображения немного отличается:

• Вместо системного события здесь всегда отображается индивидуальное название профиля, которое вы указали при его создании.
• Профиль может иметь только два статуса —ON (активный) или OFF(деактивирован). Статуса «Не настроено» здесь нет, так как каждый созданный вручную профиль уже содержит определенную логику

• Название — название профиля
• Переключатель «Автозапуск» импорта, когда включено, импорт будет запускаться автоматически, в соответствии с настройками «Когда запускать». Отображается лишь после сохранения настроек

«Когда запускать импорт» — когда именно запускать импорт автоматически, присутствует 2 варианта:
— установить время, в которое импорт должен запускаться автоматически каждый день, можно использовать, например, для передачи номеров в обзвон;
— задать период, с которым импорт будет запускаться (в минутах), время считается от последнего запуска, для примера, можно использовать как: воронка имеет значения 1 и 2 — добавить номер в обзвон 1, воронка имеет значение 3 — добавить номер в обзвон 2;
Ввиду того, что активным (в процессе выгрузки) может быть всего 1 импорт, подобный период не может гарантировать строго определенное начало работы в определенное нами время, ввиду того, что в данный момент времени может использоваться другой профиль импорта (так, например, вместо 15 определенных минут импорт данного профиля с периода может начаться позже, через 20, 25 минут etc.)

Искать по полю по времени — поиск сущностей возможен лишь за полями которые имеют тип «Дата и время»

Время от, Время до — диапазон времени, за которым будет совершаться поиск. Указать можно опционально одну или две границы поиска. Указать можно точно время или сдвиг времени (за последние 24 часа etc.)

Обработчики событий — возможность выбрать до 10 обработчиков событий, которые будут срабатывать в дальнейшем

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

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

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

Пауза между запросами к API CRM (сек) — пауза между запросами к API, обязательная, от 1 до 15 секунд

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

После сохранения настроек импорта появится кнопка Начать импорт — возможность начать импорт прямо сейчас, вручную. Работает импорт по следующему принципу:
1) Выгружаем сущности из СРМ по фильтрам по полю с временем, за 1 API запрос, 50 сущностей;
2) Каждая из найденных сущностей обрабатывается в очереди. 
Проверяется, записано ли в сущности «Время обработки» и если да и в настройке «Повторно обработать сущность если прошло N дней» не задано или не прошло N дней — ничего не делаем

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

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

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

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

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

Вебхук должен отправляться методом GET или POST. 

В запросе должен передаваться идентификатор сущности. Он может находиться:

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

Идентификатор должен передаваться в параметре с именем id или entityId. Регистр символов не имеет значения, поэтому значения ID, EntityId, ENTITYID и аналогичные считаются валидными.

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

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

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

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

Настройки со стороны KeyCRM

1. Перейдите в «Настройки» — «Дополнительно», затем перейдите на вкладку «Автоматизация» и нажмите «Добавить триггер»

2. В окне создания триггера заполните основные параметры:

• В поле «Название» укажите любое название триггера, например «Webhook при изменении статуса заказа».
• В поле «Событие» выберите, в отношении какого типа сущностей будет отправляться вебхук, и в отношении какого именно «изменения» — возьмем, например, «Заказы/Смена статуса заказа», — и выберите нужное значение, возьмем для примера «Виготовлено».
• В поле «Время выполнения» оставьте значение «Сразу», чтобы вебхук отправлялся сразу после изменения статуса (или, при необходимости, установите задержку — через сколько минут после события сработает триггер).
• В блоке «Условия для выполнения» нажмите «Добавить группу условий» и добавьте как минимум одно условие. В данном примере используется условие по статусу заказа. Наше условие будет выглядеть так: Статус заказа — содержит — «Виготовлено».
• В блоке «Действия» нажмите «Добавить действие».

4. Следующим шагом необходимо настроить саму отправку веб-хука:

• Ссылка на Webhook —сюда нужно вставить ранее скопированную ссылку из личного кабинета, из настроек соответствующего профиля обработчика (URL вебхука) 
• HTTP метод запроса — выбираем POST

После настройки нажимаем внизу «Добавить»