Карточка звонка
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Scope:
placement— регистрация точки встраивания,telephony— регистрация звонка, поднимающего карточкуКто может выполнять команды: сотрудник, которому Битрикс24 показал карточку, если у него есть доступ к приложению
Карточка звонка — окно, в котором оператор видит звонок и управляет им: отвечает, завершает разговор, ставит на удержание или переводит коллеге. Приложение телефонии со своим WebRTC-клиентом меняет заголовок, текст статуса и набор кнопок карточки. О нажатиях кнопок приложение узнает из событий и само выполняет действие со звонком, например завершает его в своем клиенте. Кнопку «Закрыть» Битрикс24 обрабатывает и сам: она отправляет событие и закрывает карточку.
Управлять можно только карточкой внешнего звонка. Приложение регистрирует звонок методом telephony.externalCall.register, и Битрикс24 показывает карточку оператору — сотруднику из параметра USER_ID или USER_PHONE_INNER этого метода. Показ зависит от параметра SHOW: по умолчанию он равен 1, а при 0 карточка появится только после вызова метода telephony.externalCall.show. Команды и события идут через фоновый обработчик в точке встраивания PAGE_BACKGROUND_WORKER.
Команды управления карточкой начинают работать после события BackgroundCallCard::initialized: оно приходит, когда карточка создана. До этого события, после закрытия карточки и при обычном звонке Битрикс24 они вернут ошибку Call card is undefined. Команда CallCardGetListUiStates работает и без карточки.
Порядок регистрации обработчика описан на странице Сценарий встраивания WebRTC, все команды и события — в обзоре раздела Управление карточкой звонка WebRTC-клиента: обзор команд и событий.
Из чего состоит карточка
Так выглядит карточка входящего звонка:
Чтобы изменить заголовок в верхней части карточки, вызовите команду CallCardSetCardTitle и передайте объект со свойством title.
BX24.placement.call('CallCardSetCardTitle', { title: 'Card Title' }, (result) => {
console.log(result); // [] — заголовок изменен
});
Чтобы изменить текст статуса под именем собеседника, вызовите команду CallCardSetStatusText и передайте объект со свойством statusText.
BX24.placement.call('CallCardSetStatusText', { statusText: 'Status Text' }, (result) => {
console.log(result); // [] — текст изменен
});
Кнопки внизу карточки зависят от состояния интерфейса. Команда CallCardGetListUiStates возвращает 12 состояний, в которые приложение может перевести карточку: в функцию обратного вызова придет массив их кодов.
BX24.placement.call('CallCardGetListUiStates', {}, (data) => {
console.log(data);
});
Переход на другое состояние карточки выполняет команда CallCardSetUiState: передайте ей объект со свойством uiState.
BX24.placement.call('CallCardSetUiState', { uiState: 'connected' }, (result) => {
console.log(result); // [] — состояние изменено
});
Чтобы узнавать, какие кнопки нажимает оператор, подпишитесь на события методом BX24.placement.bindEvent. Какое событие отправляет каждая кнопка, показано в таблице ниже, описание событий — в разделе Обзор событий при работе с карточкой звонка WebRTC-клиента.
Состояния карточки
Сразу после появления карточка находится в служебном состоянии: внизу у нее только кнопка «Закрыть». Этого состояния нет ни в таблице ниже, ни в ответе команды CallCardGetListUiStates. Чтобы показать оператору нужные кнопки, переведите карточку в одно из состояний командой CallCardSetUiState.
|
Состояние |
Когда используется |
Кнопки и события |
|
incoming |
Для принятия входящих звонков |
|
|
transferIncoming |
Для принятия перенаправленного входящего звонка |
|
|
outgoing |
Для показа карточки исходящего звонка |
|
|
connectingIncoming |
Для показа карточки в момент подключения к входящему звонку |
|
|
connectingOutgoing |
Для показа карточки в момент подключения к исходящему звонку |
|
|
connected |
Для показа после подключения к звонку |
|
|
transferring |
Для подтверждения перенаправления звонка на другого оператора |
|
|
transferFailed |
Если перенаправить звонок не получилось |
|
|
transferConnected |
Если перенаправление завершилось успешно и нужно выйти из карточки звонка |
|
|
error |
Если произошла ошибка звонка |
|
|
moneyError |
Если на счету закончились деньги и нужно сообщить об этом администратору Битрикс24 |
|
|
redial |
Если абонент занят и оператору нужно позвонить на этот номер еще раз, не закрывая карточку звонка |
|
Индикатор качества связи в состоянии connected нажатий не принимает и события не отправляет.
Таймер разговора
При переходе в состояние connected таймер разговора запускается сам. Чтобы он не запускался, передайте вместе с uiState: 'connected' свойство disableAutoStartTimer: true.
В состояниях перевода звонка — transferring, transferFailed и transferConnected — отсчет продолжается. Остальные состояния, кроме connected, таймер останавливают. Остановить или снова запустить таймер можно командами CallCardStopTimer и CallCardStartTimer.
Продолжите изучение
- Управление карточкой звонка WebRTC-клиента: обзор команд и событий
- Обзор событий при работе с карточкой звонка WebRTC-клиента
- Изменить состояние интерфейса карточки звонка со стороны приложения CallCardSetUiState
- Сценарий встраивания WebRTC
