Интеграция Битрикс24 с Ростелеком Виртуальная АТС

Интеграция Битрикс24 с Ростелеком Виртуальная АТС

Ростелеком ВАТС — продукт крупнейшего российского телекоммуникационного оператора. Для компаний с государственным или корпоративным уклоном, которые по умолчанию работают с Ростелекомом, интеграция виртуальной АТС с Битрикс24 — стандартный запрос при внедрении CRM.

Особенности API Ростелеком ВАТС

Ростелеком предоставляет ВАТС API с поддержкой webhooks. Личный кабинет ВАТС Ростелеком расположен по адресу vats.rt.ru. Раздел для настройки интеграции: Настройки → Интеграции → Веб-хуки.

Авторизация запросов от Ростелекома: входящие webhooks от Ростелекома подписываются X-Signature в заголовке. Ключ для проверки подписи получается в личном кабинете.

Проверка подписи:

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

Структура события от Ростелекома ВАТС:

{
  "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"
}

Разница между duration_full и duration_talk

Это важно для Битрикс24: duration_full — от начала звонка до его завершения (включая время ожидания в очереди/IVR). duration_talk — только разговор. В telephony.externalcall.finish передаётся DURATION — для корректной аналитики в CRM передавайте duration_talk, а не duration_full.

Записи разговоров через API

Ростелеком хранит записи и предоставляет API для их получения. По record_id из события end запрашивается файл:

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

Ответ — прямая ссылка на аудиофайл или сам файл в теле ответа (зависит от версии API). Ссылка действительна ограниченное время (обычно 1 час) — скачивать нужно сразу после получения события.

Исходящие через API Ростелеком

Click-to-call через Ростелеком ВАТС API:

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

Ростелеком перезванивает на телефон сотрудника, затем соединяет с клиентом. Ответ API содержит call_uuid для отслеживания события звонка.

Работа с несколькими сотрудниками в одном звонке

Ростелеком ВАТС поддерживает перевод звонков между сотрудниками (attended и blind transfer). При переводе приходит отдельное событие transfer. Для Битрикс24 это означает смену USER_ID активного звонка.

Обработка перевода:

1. Событие transfer содержит исходный call_uuid и новый extension принявшего сотрудника.
2. Достаём bitrix_call_id по исходному call_uuid.
3. Вызываем telephony.externalcall.update для обновления ответственного.

Если API Битрикс24 не поддерживает обновление пользователя в активном звонке, решение — завершить исходный звонок и зарегистрировать новый. Это создаёт две записи в истории, что неудобно. Альтернатива: использовать кастомное поле «Перевёл звонок» в звонке и фиксировать цепочку переводов.

Кейс: государственная структура, 50 сотрудников

Региональное государственное учреждение с номерами Ростелеком и требованием хранить записи всех звонков. В Ростелеком ВАТС записи хранятся 90 дней, затем удаляются. Требование регулятора — 3 года хранения.

Решение: при каждом событии end с записью обработчик скачивает файл и загружает его в корпоративное S3-хранилище (MinIO). В Битрикс24 прикрепляется не ссылка на Ростелеком, а постоянная ссылка на внутреннее хранилище. Через 90 дней ссылка на Ростелеком становится недействительной, но в Битрикс24 запись по-прежнему доступна через внутреннюю ссылку.

Срок настройки: 5-7 рабочих дней.