REST: телефония (telephony)

Scope telephony позволяет подружить Битрикс24 с любой сторонней АТС. Через REST регистрируют входящие и исходящие вызовы, показывают карточку клиента, прикрепляют запись разговора и снимают статистику. Разберём ключевые методы и события.

Модель интеграции телефонии

Есть два пути. Первый — облачная телефония на базе Voximplant (методы voximplant.*). Второй, чаще востребованный интеграторами, — подключение внешней АТС (Asterisk, FreePBX, облачные операторы) через методы telephony.external*.

Логика внешней АТС проста: сторонняя система сообщает Битрикс24 о начале и конце звонка, а Битрикс24 показывает всплывающую карточку и создаёт запись в статистике и CRM. Для доступа нужен scope telephony.

Выбор модели определяет объём работы. Voximplant избавляет от согласования линий и берёт на себя маршрутизацию, но привязывает вас к встроенному оператору. Внешняя АТС даёт полный контроль над телефонией и позволяет сохранить действующего провайдера и номерную ёмкость, но всю логику связки со всплывающими карточками и CRM вы реализуете сами через методы telephony.external*. Для крупных колл-центров второй путь почти всегда предпочтительнее.

Внешние линии

Прежде чем регистрировать звонки, заведите внешнюю линию — к ней будут привязаны все вызовы вашей АТС:

• telephony.externalLine.add — создать линию (передаётся NUMBER и NAME);
• telephony.externalLine.get — список линий портала;
• telephony.externalLine.delete — удалить линию по номеру.

telephony.externalLine.add(NUMBER: "main_office", NAME: "Городской 495")

Жизненный цикл звонка

Каждый вызов проходит три шага: регистрация, показ карточки, завершение с итогами. Порядок методов:

1. telephony.externalCall.register — регистрируем вызов, получаем CALL_ID. Передаём USER_ID, PHONE_NUMBER, TYPE (1 — исходящий, 2 — входящий), LINE_NUMBER;
2. telephony.externalCall.show — показываем всплывающую карточку менеджеру по CALL_ID и USER_ID;
3. telephony.externalCall.finish — закрываем звонок с длительностью, статусом и стоимостью.

При регистрации ключевой параметр — CRM_CREATE: если 1, Битрикс24 сам создаст лид по неизвестному номеру.

Важно сохранять CALL_ID из ответа register на стороне АТС и передавать его во все последующие вызовы — именно он связывает показ карточки, запись и завершение в единый звонок. Если пропустить шаг регистрации и сразу вызвать finish, звонок не попадёт в детализацию корректно. Для входящих вызовов регистрацию делают в момент поступления звонка на АТС, для исходящих — при снятии трубки менеджером. Параметр SHOW при регистрации управляет тем, показывать ли карточку автоматически или отдельным вызовом show.

Завершение и коды статусов

Метод telephony.externalCall.finish фиксирует результат. Важно правильно передать код завершения — от него зависит, как звонок отображается в отчётах.

telephony.externalCall.finish(CALL_ID: "x1a...", USER_ID: 5, DURATION: 63, STATUS_CODE: "200", COST: 4.5)

Запись разговора

Файл записи прикрепляется к уже завершённому звонку методом telephony.externalCall.attachRecord. Передать можно либо ссылку, либо контент в base64:

telephony.externalCall.attachRecord(CALL_ID: "x1a...", FILENAME: "rec.mp3", RECORD_URL: "https://ats/rec/998.mp3")

Прикреплять запись нужно после finish, когда звонок уже закрыт и существует в детализации. Если АТС отдаёт запись с задержкой (файл дописывается после разговора), делайте отдельную отложенную задачу, которая дозагрузит запись по сохранённому CALL_ID. Формат файла — обычно mp3 или wav; ссылка RECORD_URL должна быть доступна серверам Битрикс24 на момент вызова, иначе запись не подтянется.

События и Voximplant

Реактивную логику строят на событиях телефонии — они приходят на обработчик, зарегистрированный через event.bind:

• OnExternalCallStart — АТС Битрикс24 инициирует исходящий (для click-to-call);
• OnVoximplantCallInit / OnVoximplantCallStart / OnVoximplantCallEnd — этапы облачного вызова.

Для облачной телефонии полезны voximplant.statistic.get (детализация звонков с фильтром по дате и типу), voximplant.line.get (список номеров) и voximplant.url.get (ссылки на страницы настроек). Метод telephony.externalCall.searchCrmEntities помогает найти, к какой CRM-сущности привязать вызов.

События приходят офлайн-обработчику приложения, поэтому телефонное приложение обычно регистрируют как локальное с указанием обработчика событий. На OnExternalCallStart ваш сервер получает USER_ID и набранный номер, инициирует звонок на АТС и возвращает управление. Это и есть механика click-to-call: менеджер жмёт на номер в карточке CRM, а трубку поднимает его физический или софтфон. Для голосовых меню и роботизированных обзвонов дополнительно применяют TTS-методы voximplant.tts.voices.get.

Итог

Scope telephony — это компактный, но полный набор: внешние линии, регистрация и завершение звонков с корректными кодами, запись разговора и события для реактивной автоматики. Для облачной телефонии добавляются методы voximplant.* со статистикой. Такой связки достаточно, чтобы любая АТС «жила» внутри Битрикс24 — с всплывающими карточками, лидами и записями.

В B2Bsite мы подключаем внешние АТС и операторов к Битрикс24 под ключ: настраиваем маршрутизацию, привязку к CRM, запись и отчётность. Если телефония должна работать без разрывов и потерянных звонков — поможем спроектировать и внедрить интеграцию.