Інтеграція Бітрікс24 з Mango Office

Інтеграція Бітрікс24 з Mango Office

Mango Office — один із найпоширеніших хмарних провайдерів віртуальної АТС у Росії. В маркетплейсі Бітрікс24 є офіційний застосунок Mango Office, що спрощує базове налаштування. Але стандартний застосунок закриває не всі сценарії — при нестандартних вимогах до маршрутизації або 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 робочих днів.