Integrating Bitrix24 with Mango Office

Bitrix24 Integration with Mango Office

Mango Office is one of the most widely used cloud virtual PBX providers in Russia. There is an official Mango Office application in the Bitrix24 marketplace, which simplifies basic configuration. However, the standard application does not cover all scenarios — for non-standard routing or CRM logic requirements, a custom integration is built via the Mango API and Bitrix24 REST API.

Official Application: What Works Out of the Box

The Mango Office application is installed from the Bitrix24 catalog (Applications → Marketplace → Mango Office). After authorizing in your Mango account:

• Incoming calls create a pop-up card in Bitrix24
• Missed calls create leads or activities (configurable)
• Call history is saved in the CRM
• Outbound calls from a CRM card are initiated via Mango

Limitations of the official application:

• No flexible rules for lead/deal creation
• Employee mapping works only when Mango and Bitrix24 extension numbers match exactly
• Call recordings are attached with a delay (sometimes up to 30 minutes)
• No support for multiple Mango virtual PBXs on a single Bitrix24 portal

Mango Office API: Custom Integration

Mango provides a VPBX API with webhooks. To register a webhook in your Mango account: PBX → Settings → Notifications → Notification URL

Mango supports the following events:

• call_start — call started (not yet answered)
• call_answer — operator answered
• call_end — call ended
• call_record — recording is ready (a separate event with a link to the file)

Mango specifics: the call_record event arrives separately from call_end — 1–10 minutes after the call ends. This must be accounted for in the architecture: the recording cannot be attached synchronously upon call completion.

Structure of the call_end event from 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"
}

Employee Mapping: The Key Configuration

In Mango Office, each employee has an extension number. In Bitrix24, employees are identified by USER_ID. The integration must know the mapping between them.

The mapping table is stored in the handler configuration:

If no match is found (a new employee, or the call went to a queue and nobody answered) — a missed call is created and assigned to the default responsible user.

Recording Handling: Deferred Attachment

Since the call_record event arrives separately, a task queue is needed:

1. call_end → register call completion in Bitrix24, save the pair {mango_uuid → bitrix_call_id} in Redis/DB.
2. call_record (1–10 min later) → retrieve bitrix_call_id by mango_uuid, download the recording from the URL in the event, upload to Bitrix24 via telephony.externalCall.attachRecord.

The recording URL in the call_record event is temporary (usually valid for 24 hours). If it is not downloaded in time, the recording will be unavailable. Alternative: save the URL and download it via a scheduled job within the next few hours.

Multiple Mango PBXs on One Portal

This scenario applies to companies with multiple legal entities or multiple offices under different numbers. The standard Mango application does not support this.

Custom integration: each Mango PBX is configured to point to its own handler endpoint. Handlers split traffic flows by determining the LINE_NUMBER in Bitrix24 based on the request source (by handler URL or by a URL webhook parameter).

Case Study: Insurance Broker, 3 Offices

A company with three offices in different cities, each with a separate Mango number. Requirement: a call to the Moscow number should be created for a Moscow manager, and to the Krasnodar number — for a Krasnodar manager, even if the calls are physically handled by a single group of operators.

Solution: three separate webhook URLs in Mango (one per PBX). Each handler passes the LINE_NUMBER of the corresponding line when registering the call in Bitrix24. In the Bitrix24 telephony settings, each line has the responsible employees of that office configured. Routing works automatically.

Additional task: when a call is transferred in Mango between offices, the responsible user in Bitrix24 needed to be reassigned. Implemented by tracking the call_transfer event in the Mango API — when triggered, the USER_ID in the active Bitrix24 call is updated.

Custom integration setup time: 5–8 business days.