Интеграция Битрикс24 с Mango Office

Интеграция Битрикс24 с Mango Office

Mango Office — один из наиболее распространённых облачных провайдеров виртуальной АТС в России. Есть официальное приложение Mango Office в маркетплейсе Битрикс24, что упрощает базовую настройку. Но стандартное приложение закрывает не все сценарии — при нестандартных требованиях к маршрутизации или CRM-логике приходится строить кастомную интеграцию через API Mango и REST API Битрикс24.

Официальное приложение: что работает из коробки

Приложение Mango Office устанавливается из каталога Битрикс24 (Приложения → Маркетплейс → Mango Office). После авторизации в личном кабинете Mango:

• Входящие звонки создают всплывающую карточку в Битрикс24
• Пропущенные звонки создают лиды или дела (настраивается)
• История звонков сохраняется в CRM
• Исходящий звонок из карточки CRM инициируется через Mango

Ограничения официального приложения:

• Нет гибкой настройки правил создания лидов/сделок
• Маппинг сотрудников работает только при полном совпадении внутренних номеров Mango и Битрикс24
• Запись звонков прикрепляется с задержкой (иногда до 30 минут)
• Нет поддержки нескольких виртуальных АТС Mango на один портал Битрикс24

API Mango Office: самостоятельная интеграция

Mango предоставляет VPBX API с webhooks. Для регистрации webhook в личном кабинете Mango: АТС → Настройки → Уведомления → URL для уведомлений

Mango поддерживает события:

• call_start — звонок начался (ещё не отвечен)
• call_answer — оператор ответил
• call_end — звонок завершён
• call_record — запись готова (отдельное событие с ссылкой на файл)

Особенность Mango: событие call_record приходит отдельно от call_end — через 1-10 минут после завершения звонка. Это нужно учитывать в архитектуре: нельзя прикрепить запись синхронно при завершении звонка.

Структура события call_end от Mango:

{
  "uuid": "unique-call-id",
  "start_time": 1705308600,
  "finish_time": 1705308785,
  "duration": 185,
  "from": {"number": "+74951234567"},
  "to": {"number": "101", "extension": "101"},
  "entry_id": "100200",
  "call_direction": "in",
  "call_state": "Answered"
}

Маппинг сотрудников: ключевая настройка

В Mango Office каждый сотрудник имеет внутренний номер (extension). В Битрикс24 — ID пользователя. Интеграция должна знать соответствие.

Таблица маппинга хранится в конфигурации обработчика:

Если соответствие не найдено (новый сотрудник, или звонок попал в очередь и никто не ответил) — создаётся пропущенный звонок с привязкой к ответственному по умолчанию.

Обработка записей: отложенное прикрепление

Поскольку событие call_record приходит отдельно, нужна очередь задач:

1. call_end → регистрируем завершение звонка в Битрикс24, сохраняем пару {mango_uuid → bitrix_call_id} в Redis/БД.
2. call_record (через 1-10 мин) → достаём bitrix_call_id по mango_uuid, скачиваем запись по ссылке из события, загружаем в Битрикс24 через telephony.externalCall.attachRecord.

Ссылка на запись в событии call_record — временная (обычно 24 часа). Если не успеть скачать — запись будет недоступна. Альтернатива: сохранять URL и скачивать через регламентное задание в течение ближайших часов.

Несколько АТС Mango на один портал

Сценарий актуален для компаний с несколькими юрлицами или несколькими офисами под разными номерами. Стандартное приложение Mango не поддерживает это.

Кастомная интеграция: каждая АТС Mango настраивается на свой endpoint обработчика. Обработчики разделяют потоки, определяя LINE_NUMBER в Битрикс24 по источнику запроса (по URL обработчика или по параметру в URL webhook).

Кейс: страховой брокер, 3 офиса

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

Решение: три отдельных webhook URL в Mango (по одному на каждую АТС). Каждый обработчик при регистрации звонка в Битрикс24 передаёт LINE_NUMBER соответствующей линии. В настройках телефонии Битрикс24 для каждой линии прописаны ответственные сотрудники данного офиса. Маршрутизация работает автоматически.

Дополнительная задача: при переводе звонка из Mango между офисами нужно было переназначить ответственного в Битрикс24. Реализовали через отслеживание события call_transfer в API Mango — при его наступлении обновляем USER_ID в активном звонке Битрикс24.

Срок настройки кастомной интеграции: 5-8 рабочих дней.