Integration of Bitrix24 with Rostelecom Virtual PBX

Bitrix24 Integration with Rostelecom Virtual PBX

Rostelecom Virtual PBX is a product from Russia's largest telecommunications operator. For companies with a government or enterprise focus that work with Rostelecom by default, integrating the virtual PBX with Bitrix24 is a standard request during CRM implementation.

Rostelecom Virtual PBX API Features

Rostelecom provides a Virtual PBX API with webhook support. The Rostelecom Virtual PBX management portal is located at vats.rt.ru. The integration configuration section: Settings → Integrations → Webhooks.

Authorization of requests from Rostelecom: incoming webhooks from Rostelecom are signed with X-Signature in the header. The key for signature verification is obtained in the management portal.

Signature verification:

$expectedSig = hash_hmac('sha256', $rawBody, $webhookKey);
if (!hash_equals($expectedSig, $request->header('X-Signature'))) {
    abort(403);
}

Structure of an event from Rostelecom Virtual PBX:

{
  "event": "end",
  "call_uuid": "rt-abc123def456",
  "call_direction": "inbound",
  "caller_id": "+74951234567",
  "called_number": "+74997654321",
  "extension": "103",
  "call_start": "2024-01-15T10:30:00+03:00",
  "call_answer": "2024-01-15T10:30:15+03:00",
  "call_end": "2024-01-15T10:33:05+03:00",
  "duration_full": 185,
  "duration_talk": 170,
  "record_id": "record-uuid-12345"
}

The Difference Between duration_full and duration_talk

This matters for Bitrix24: duration_full — from the start of the call to its end (including queue/IVR wait time). duration_talk — the actual conversation only. The DURATION field in telephony.externalcall.finish should use duration_talk, not duration_full, for accurate CRM analytics.

Call Recordings via API

Rostelecom stores recordings and provides an API to retrieve them. The file is requested by record_id from the end event:

GET https://api.vats.rt.ru/v2/records/{record_id}
Authorization: Bearer {access_token}

The response is either a direct link to the audio file or the file itself in the response body (depends on API version). The link is valid for a limited time (usually 1 hour) — download immediately after receiving the event.

Outbound Calls via Rostelecom API

Click-to-call via Rostelecom Virtual PBX API:

POST https://api.vats.rt.ru/v2/calls/originate
Authorization: Bearer {access_token}
{
  "from_extension": "103",
  "to_number": "+74951234567"
}

Rostelecom calls the employee's phone first, then connects them to the client. The API response contains call_uuid for tracking the call event.

Handling Multiple Employees in a Single Call

Rostelecom Virtual PBX supports call transfers between employees (attended and blind transfer). A separate transfer event is sent upon transfer. For Bitrix24, this means changing the USER_ID of the active call.

Handling a transfer:

1. The transfer event contains the original call_uuid and the new extension of the employee who accepted the transfer.
2. Retrieve bitrix_call_id using the original call_uuid.
3. Call telephony.externalcall.update to update the responsible user.

If the Bitrix24 API does not support updating the user on an active call, the workaround is to end the original call and register a new one. This creates two records in the history, which is inconvenient. Alternative: use a custom field "Call Transferred By" on the call record and log the transfer chain.

Case Study: Government Organization, 50 Employees

A regional government agency with Rostelecom numbers and a requirement to store recordings of all calls. Rostelecom Virtual PBX retains recordings for 90 days, after which they are deleted. The regulatory requirement was 3 years of retention.

Solution: on every end event with a recording, the handler downloads the file and uploads it to a corporate S3 storage (MinIO). In Bitrix24, instead of a Rostelecom link, a permanent link to the internal storage is attached. After 90 days the Rostelecom link becomes invalid, but the recording in Bitrix24 remains accessible via the internal link.

Setup time: 5–7 business days.