Integration of Bitrix24 with Megafon Virtual PBX

Bitrix24 Integration with MegaFon Virtual PBX

MegaFon Virtual PBX is a cloud telephony service from one of Russia's largest mobile operators. For companies that already have their corporate numbers with MegaFon, this is the natural choice for a virtual PBX. The integration with Bitrix24 is built via the MegaFon API, which provides webhooks for call events.

How MegaFon Delivers Events

MegaFon Virtual PBX works with push notifications (webhooks). The notification URL for one or more event types is configured in the management portal:

MegaFon specifics: all events for a single call are linked via a common call_id. This is convenient — no need to generate your own identifier to correlate events.

Example notification from MegaFon on call end:

{
  "type": "end",
  "call_id": "meg_0123456789abcdef",
  "start_time": "2024-01-15 10:30:00",
  "end_time": "2024-01-15 10:33:05",
  "duration": 185,
  "from_number": "+74951234567",
  "to_number": "+74992345678",
  "internal_number": "102",
  "state": "answered",
  "direction": "in"
}

Handler Configuration

The handler receives POST requests from MegaFon and translates events into Bitrix24.

On answer event (operator picked up):

• Determine USER_ID in Bitrix24 by internal_number
• Call telephony.externalcall.register
• Save the pair {meg_call_id → bitrix_call_id} in storage

On end event:

• Retrieve bitrix_call_id by meg_call_id
• Determine STATUS_CODE from the state field:
  • answered → 200
  • not_answered → 304 (missed)
  • busy → 486
• Call telephony.externalcall.finish

On record event (arrives a few minutes after end):

• Retrieve bitrix_call_id by call_id
• Download the recording from the URL in the event
• Upload via telephony.externalCall.attachRecord

MegaFon provides the recording URL in this format:

{
  "type": "record",
  "call_id": "meg_0123456789abcdef",
  "url": "https://vats.megafon.ru/records/...",
  "duration": 185
}

Outbound Calls via MegaFon Virtual PBX

MegaFon supports an API for initiating outbound calls (click-to-call). The manager clicks on a number in Bitrix24, Bitrix24 passes the event to the handler, and the handler calls the MegaFon API:

POST https://vats.megafon.ru/v1/click2call
{
  "from": "102",         // employee's extension number
  "to": "+74951234567",  // client's number
  "line_id": "000001"    // line ID
}

MegaFon first calls the employee's phone, then connects them to the client. At this point the handler must register the outbound call in Bitrix24 via telephony.externalcall.register with TYPE=2 (outbound).

Configuration in the MegaFon Virtual PBX Portal

In the Integrations → Notifications section:

1. Event URL — your handler address
2. Format — JSON
3. Secret key (HMAC signature of requests) — for verifying requests from MegaFon

Signature verification is mandatory; otherwise the handler will accept any POST request from anyone:

$signature = hash_hmac('sha256', $rawBody, $secretKey);
if ($signature !== $_SERVER['HTTP_X_MEGAFON_SIGNATURE']) {
    http_response_code(403);
    exit;
}

Case Study: Medical Clinic, 8 Administrators

A clinic used MegaFon Virtual PBX with 8 extensions and IVR for two specializations. The issue: a call could pass through IVR and a queue before reaching an administrator. The requirement was to record in Bitrix24 the extension number of the employee who actually answered, not the initial distribution number.

MegaFon passes the number of the last answering subscriber in the internal_number field — which is exactly what was needed. Additionally: if the client hung up in the IVR (before entering the queue), the end event arrives with state=not_answered and an empty internal_number. In this case, a missed call is created with no responsible employee — it appears in the general list for the reception administrator.

Setup time: 4–5 business days.