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

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

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

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

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

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

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

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

1. Нажмите «Подключить интеграцию с Bitrix24» и в настройках подключения укажите адрес вашего портала в формате:

https://your-domain.bitrix24.com
http://your-domain.bitrix24.com

Если вы используете коробочную версию Bitrix24 и испытываете сложности с SSL-сертификатом, допускается использование HTTP-адреса.

3. При нажатии «Подключить» будет совершён переход на страницу соответсвенной CRM для продолжения подключения (Установить приложение UniTalk и предоставить права на работу приложения)

Нажмите на кнопку «Install«

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

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

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

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

• Лиды
• Сделки
• Контакты
• Компании
• Коммерческие предложения
• Счета

так и с пользовательскими сущностями.

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

Особенности сущностей в Bitrix24

При настройке Omni-интеграции для Bitrix24 важно различать типы доступных сущностей

• Базовые сущности: лид, сделка, контакт, компания, предложение, счет.
• Кастомные (пользовательские) сущности: в системе Битрикс они называются смарт-процессами. Вы можете легко создать собственную уникальную сущность непосредственно внутри CRM во вкладке Smart process automation (Автоматизация смарт-процессов), и интеграция сможет полноценно с ней работать.

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

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

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

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

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

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

Как работает приоритет: Чем выше в списке расположено поле с выбранной сущностью (сделка, лид, контакт и т.д.), тем более высокий приоритет она имеет для системы при определении ответственного менеджера и срабатывании функции «липучки».

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

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

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

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

Для CRM Битрикс реализован детализированный поиск по отдельным сущностям:

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

• Если ваша интеграция с 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 и пользователями в системе UniTalk. Настройка выполнена в виде таблицы, где каждая колонка отвечает за конкретные данные:

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

Настройка форматов номеров телефонов для поиска

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

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

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

Как работают шаблоны и логика подстановки звездочек *

В шаблоне разрешается использовать одиночные пробелы, цифры, а также символы , +, -, (, ). Например: +38 () ***—.

Логика подстановки цифр вместо звездочек (*) работает с конца номера телефона к концу шаблона.

Вместе пошагово разберем пример, где задан шаблон *** ***—, а клиент звонит с номера 380971234567:

1. *** **—67
2. *** ***—*7
3. *** ***-*5-67
4. *** ***-45-67
5. *** 3-45-67
6. *** *23-45-67
7. *** 123-45-67
8. 7 123-45-67
9. *97 123-45-67
10. 097 123-45-67
11. На этом процесс завершается. Шаблон полностью заполнен цифрами, а остаток номера (38) система просто отбрасывает.

Что будет, если звездочек больше, чем цифр? Если в вашем шаблоне символов * больше, чем реальных цифр в номере телефона, то все лишние звездочки при подстановке будут просто удалены системой. Например, если шаблон состоит из 15 звездочек ***************, а входящий номер содержит всего 10 цифр (0123456789), то после подстановки в шаблон он так и останется чистым номером 0123456789.

Настройка профилей действий

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

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

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

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

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

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

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

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

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

1. Звонки Click-to-Call (C2C): Раньше при запланированном C2C-звонке сущности создавались автоматически и к ним добавлялся стандартный комментарий. В Omni-интеграциях автоматических действий нет — теперь вы самостоятельно и гибко настраиваете нужную вам цепочку событий.
2. Разделение событий: Раньше все 6 событий звонка были объединены в один общий алгоритм, а сущности для исходящих создавались только при наличии одной общей галочки. Старая логика отрабатывала только один раз за звонок (в момент ответа, а если не ответили — в момент завершения).
3. Гибкость и безопасность настроек: В новом интеграции технически можно настроить создание сущностей хоть на каждое событие (2 раза при входящем и 3 раза при исходящем). Однако мы настоятельно рекомендуем так не делать, чтобы избежать хаоса и потенциальных ошибок в CRM.

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

Важное правило: Использовать профили из этой вкладки можно исключительно в общих обработчиках событий UniTalk, выбирая тип действия «Выполнить действия через Omni-интеграцию».

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

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

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

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

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

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

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

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

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

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

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

• Не настроено — вы еще не задавали правил и логики для этого профиля действий.
• 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. При необходимости можно добавить поддержку других HTTP-методов, однако на текущий момент такой потребности не предусмотрено.

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

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

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

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

Для интеграции с Bitrix24 также выполняется поиск параметра data[FIELDS][ID], поскольку именно в таком формате Bitrix24 передает идентификатор сущности в вебхуках создания объектов, и изменить название параметра невозможно.

Передача данных в обработчик событий не гарантирует выполнение действия обработчиком. Решение о выполнении конкретного действия принимается непосредственно в логике обработки события.

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

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

Перейдите «Приложения» -> «Разработчикам»

В Bitrix24 существует два способа настройки отправки вебхуков в зависимости от поставленной задачи:

• через автоматизацию воронок продаж (роботы);
• через глобальные инструменты разработчика.

Ниже приведены подробные пошаговые инструкции для каждого варианта настройки.

Этот способ идеально подходит в случаях, когда действие UniTalk должно выполняться при переводе лида или сделки на определенный этап воронки продаж (например, при переходе сделки на этап «Требуется обзвон» или «Успешно реализовано»).

1. Откройте Bitrix24 и перейдите в раздел Лиды или Сделки.
2. В правом верхнем углу рабочего пространства нажмите кнопку Automation Rules (в локализованных версиях — Роботы или Роботы и триггеры).

Откроется окно настройки робота:

В поле для URL вставьте ранее скопированный адрес входящего вебхука из кабинета UniTalk.

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

В левом главном меню Bitrix24 найдите и перейдите в раздел Developer resources (в некоторых версиях — Приложения / Applications → вкладка Разработчикам / Developers).

В форме настройки карточки заполните поля:

• Название: укажите любое произвольное имя (например, «Входящий вебхук UniTalk»).
• URL вашего обработчика (URL обработчика): вставьте скопированный URL.
  Примечание: в этом типе настройки параметры вроде ?id= в URL добавлять не нужно — Bitrix24 автоматически передаст технический блок с ID в теле запроса (data[FIELDS][ID]).
• Токен приложения: оставьте без изменений, поле заполняется системой автоматически.

В блоке Events (События) нажмите кнопку «Добавить» или выберите из списка конкретные системные триггеры, на которые должен реагировать вебхук (например, ONCRMDEALADD — создание сделки или ONCRMCONTACTUPDATE — изменение данных контакта).