Сценарий встраивания WebRTC

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Приложение телефонии со своим WebRTC-клиентом работает с карточкой звонка Битрикс24 в два шага: регистрирует фоновый обработчик на всех страницах и поднимает карточку собственным звонком. Команды и события карточки перечислены в обзоре раздела Управление карточкой звонка WebRTC-клиента: обзор команд и событий.

Регистрация обработчика

Обработчик WebRTC-клиента регистрируется один раз и загружается на каждой странице.

Для этого есть специальная точка встраивания: она формируется невидимым фреймом на каждой странице Битрикс24. Регистрация делается так:

'placement.bind',
        [
            'PLACEMENT' => 'PAGE_BACKGROUND_WORKER',
            'HANDLER' => 'http://example.com/placement/?ty=1',
            'OPTIONS' => [
                'errorHandlerUrl' => 'http://example.com/logg.php?ty=1',
            ],
            'LANG_ALL' => [
                'ru' => [
                    'TITLE' => 'test',
                ]
            ]
        ]

Важное отличие от других точек — обязательный параметр OPTIONS[errorHandlerUrl]. Виджет загружается на каждой странице, поэтому обработчик должен отвечать быстро: если ответ идет дольше пяти секунд и это повторяется больше десяти раз за сутки на одном Битрикс24, регистрация удаляется. Об удалении Битрикс24 сообщает запросом на адрес из errorHandlerUrl, после чего обработчик нужно зарегистрировать заново. Подробнее — в статье Фоновый обработчик на всех страницах PAGE_BACKGROUND_WORKER.

Сценарий использования

Звонок регистрируют методом telephony.externalCall.register — он же поднимает карточку звонка. Вызывайте его в момент, когда WebRTC-клиент виджета начал обработку звонка.

Далее виджет может взаимодействовать с открытой карточкой звонка. Для работы с карточкой через точку встраивания PAGE_BACKGROUND_WORKER есть 9 команд js-интерфейса для получения и изменения данных карточки и 17 событий для обработки действий оператора — полный список в обзоре раздела Управление карточкой звонка WebRTC-клиента: обзор команд и событий.

Ключевое событие — BackgroundCallCard::initialized. Оно возникает при создании карточки звонка, и только после него карточкой можно управлять. Поэтому все вызовы команд со стороны приложения выполняйте в обработчике этого события.