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

Подключение 3CX к Битрикс24

Пошаговое руководство: установка приложения, создание клиентского приложения в 3CX, привязка сотрудников и настройка записей разговоров.

Шаг 1

Установка приложения из Маркетплейса Битрикс24

Установите и откройте приложение на вкладке «Подключение».

Шаг 2

Создание клиентского приложения в 3CX

2.1 Создание Service Principal

В админ-панели вашего 3CX-сервера нужно создать клиентское приложение (Service Principal). Через него 3CX Connector будет получать события звонков. По итогам шага у вас должны быть на руках три значения: URL вашего 3CX, Client ID и Client Secret.

Войдите в веб-консоль 3CX под учётной записью владельца системы (System Owner). Перейдите в Admin Console → Integrations → API и нажмите «Добавить».

Прямая ссылка имеет вид: https://ваш-3cx-сервер/#/office/integrations/api

2.2 Client ID

Client ID — числовой идентификатор для приложения. Он должен быть уникальным в вашей АТС: не совпадать ни с одним существующим внутренним номером сотрудника, очередью, ring group, IVR или другим клиентским приложением.

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

2.3 Права доступа

Включите доступ к API конфигурации (xAPI) и 3CX Call Control API. Выберите:

Подразделение — DEFAULT
Роль — Владелец системы

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

2.4 Добавочные номера

Нажмите «Выберите добавочные номера» и выберите все.

2.5 Сохранение API key

Нажмите кнопку «Сохранить» и скопируйте API key приложения.

Этот ключ показывается ровно один раз. Закроете окно без копирования — ключ будет потерян. Тогда придётся зайти в созданное приложение и нажать «Сгенерировать API ключ».

При генерации нового ключа, если интеграция уже подключена и настроена, его обязательно нужно обновить в настройках 3CX Connector — иначе интеграция перестанет работать.

2.6 Записи разговоров

Чтобы прикреплять аудиозаписи разговоров к карточкам звонков в Битрикс24, нужна отдельная авторизация в 3CX от имени учётной записи с правами на скачивание записей. Service Principal таких прав не даёт — его роль только для управления и событий.

Учётная запись должна иметь роль «Владелец системы» — это требование 3CX для доступа к записям, обойти его на стороне приложения нельзя. На этой учётной записи также не должна быть включена двухфакторная аутентификация (2FA) — иначе интеграция не сможет подключиться автоматически.

Рекомендуется создать отдельную учётную запись с ролью «Владелец системы» специально для интеграции.

Как проверить, что у учётной записи достаточно прав: войдите в веб-интерфейс 3CX под этой учётной записью. В настройках должен присутствовать пункт «Записи разговоров».

Шаг 3

Подключение в Битрикс24

3.1 Данные подключения

Введите публичный адрес вашего 3CX-сервера (без «/» в конце) и данные, которые вы получили в Шаге 2:

Client ID (Service Principal) — числовой идентификатор клиентского приложения из пункта 2.2.
Client Secret (Service Principal) — секретный API key из пункта 2.5.

3.2 Подключение записей разговоров

Если вы решили, что записи разговоров не нужны — включите тумблер «Без записей разговоров» и нажмите «Подключить».

Если записи разговоров нужны — введите логин и пароль учётной записи с ролью «Владелец системы» и нажмите «Подключить».

3.3 Управление подключением

После подключения на вкладке появляется переключатель «Включить/выключить интеграцию». Им удобно временно остановить интеграцию без сброса настроек — например, на время технических работ на стороне 3CX.

Кнопка «Сбросить подключение» полностью удаляет данные подключения. Используйте её, если хотите подключить интеграцию к другому 3CX-серверу или с другими учётными данными.

Шаг 4

Привязка сотрудников

4.1 Загрузка списка из 3CX

Перейдите на вкладку «Сотрудники» и нажмите «Обновить из 3CX». Приложение получит актуальный список пользователей с вашего 3CX-сервера.

4.2 Как сопоставляются пользователи

Каждый сотрудник из 3CX сопоставляется с пользователем Битрикса по полю «Внутренний телефон» в карточке сотрудника. Если значения совпадают — сотрудник появляется в списке как сопоставленный, и его можно активировать.

Если кого-то из 3CX в списке нет или напротив его имени написано «Нет совпадений» — откройте профиль нужного пользователя в Битрикс24, заполните поле «Внутренний телефон» его внутренним номером 3CX, сохраните и снова нажмите «Обновить из 3CX».

4.3 Активация сотрудников

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

Нажмите «Сохранить».