...
Посмотр рубрик

Встраивание WebRTC-телефона и API

3 мин. чтения

1. Общая информация и назначение #

Данное руководство содержит полное описание сценариев интеграции, настройки и управления WebRTC телефоном OKTELL, доставляемым в едином JS-файле для размещения на собственном сервере и подключения к любой web-странице.

 

2. Встраивание WebRTC телефона на страницу #

WebRTC телефон поставляется в виде одного JS-файла. Для того чтобы встроить телефон на страницу:

  1. Скопируйте файл (например, softphone-1.3.16.js) на ваш веб-сервер.

  2. Пропишите подключение телефона в нужном месте на странице:

xml
<body>
<script type="text/javascript" src="softphone-1.3.16.js"></script>
</body>

 

3. Инициализация и жизненный цикл приложения #

3.1 Ждать полной инициализации #

Вызовы к методам объекта OKTELLPhone делать только после завершения инициализации!
С версии 2.0.7 появился специальный callback:

javascript
window.OKTELLPhone.onInit = () => {
// Ваша логика после запуска приложения
}

4. Основные методы API #

API описан подробно: Методы API

4.1 Режим «noGUIMode» (урезанный интерфейс) #

Для интеграции с CRM и кастомного UI:

javascript
OKTELLPhone.noGUIMode(true); // включить урезанный режим
OKTELLPhone.noGUIMode(false); // вернуть стандартный интерфейс

4.2 Авторизация пользователя #

javascript
const user = {
username: "testuser",
password: "testpassword",
domain: "devel-connector.cloud.oktell.studio",
server: "cloud.oktell.studio",
};
OKTELLPhone.authorize(user);

4.3 Совершение и прием звонков #

  • Исходящий звонок:
    OKTELLPhone.callNumber("267");

  • Ответ на входящий:
    OKTELLPhone.answer(callid);

  • Отбой текущего:
    OKTELLPhone.endCall(callid);

  • Получить ID активного звонка:
    const callid = OKTELLPhone.getActiveCallId();

4.4 Удержание и перевод звонка #

  • Удержание звонка:

javascript
OKTELLPhone.holdToggle(callid);

  • Перевести звонок (blind transfer):

javascript
OKTELLPhone.refer({ fromID, toNumber });

4.5 DnD и mute #

  • Не беспокоить:
    OKTELLPhone.dnd(true);

  • Отключить/включить микрофон или камеру:
    OKTELLPhone.muteToggle(callid, "audio"/* или "video"*/);

4.6 Управление кодеками #

  • Установка приоритетов и включение кодеков:

javascript
OKTELLPhone.setCodecSettings({ audio: [ /* массив аудиокодеков */ ], video: [ /* массив видеокодеков */ ] });

  • Получение поддерживаемых или текущих кодеков:

javascript
OKTELLPhone.getSupportedCodecs();
OKTELLPhone.getCodecSettings();

4.7 Прочие методы #

  • Установка истории вызовов:
    OKTELLPhone.setCallHistory(array);

  • Активация autoUnhold:
    OKTELLPhone.setAutoUnhold(true);

  • Получение текущих настроек пользователя:
    OKTELLPhone.getUserSettings();

  • Логаут:
    OKTELLPhone.logout();

5. Рекомендации для разработчиков #

  • Всегда обрабатывайте ошибки (try/catch) при работе с методами.

  • Ждите полной инициализации перед вызовом любого метода.

  • Для гарантии совместимости звонков не запрещайте все кодеки, а корректно настраивайте приоритеты.

  • Перед интеграцией протестируйте поведение вторжения и удержания вне производственной среды.

6. Дополнение: Настройка и диагностика кодеков #

6.1 Основные принципы работы с кодеками в WebRTC телефоне OKTELL #

  • При инициализации и настройке телефон использует заданный перечень и приоритет кодеков — аудио и видео.

  • Если у абонентов (Point 1 ↔ Point 2) пересекаются только часть кодеков, переговоры могут быть установлены только по этим кодекам. Если пересечения нет — звонок будет отбиваться на этапе попытки установления соединения.

  • По умолчанию фильтр кодеков реализован как для исходящих, так и для входящих звонков. Это значит, что различие наборов кодеков у разных пользователей приведет к невозможности соединения между ними.

  • Сервер B2B при маршрутизации добавляет аудиокодеки G.711 alaw и mulaw во все звонки. Это часто помогает, если между поинтами не находится общий набор кодеков.

6.2 Особенности работы серверов и сценариев #

  • Если включена запись разговоров, сервер B2B будет поддерживать только определенные аудиокодеки:

    • G.722

    • G.711 alaw и ulaw

    • G.726

    • G.729

    • GSM

    • opus

    • speex

  • Если запись выключена или идет работа только с видео, обмен параметрами кодеков осуществляется напрямую между устройствами, без участия B2B.

  • В звонках в конференции или IVR сервер сам строит SDP и принимает все известные ему кодеки, что делает звонки в такие сервисы максимально совместимыми.

6.3 Практические рекомендации по настройке #

  • Рекомендуется применять фильтр кодеков только для исходящего звонка. В этом случае все входящие звонки будут приниматься устройством, сразу решая проблему неудачных соединений.

  • Для максимального шанса успешного вызова не отключайте все стандартные кодеки — на практике лучше просто поднять нужный наверх в качестве приоритетного.

  • Не используйте только “служебные” кодеки (red, rtx, ulpfec, CN, telephone-event): при их изоляции могут возникнуть ошибки соединения или отсутствие аудио/видео.

  • Для видео обязательно добавляйте как минимум VP8. H.264 рекомендуется только в тех случаях, где есть уверенность в поддержке и лицензиях; он может быть отключен на сервере по умолчанию.

  • На данный момент поддержка VP9 и AV1 находится на стадии внедрения/планирования.

  • При развертывании нового соединения всегда проверяйте сообщения SDP: совпадают ли в них наборы и приоритеты кодеков с выставленными настройками.

6.4 Диагностика проблем с кодеками #

  • Если не выбран ни один кодек, будет применяться стандартный перечень, предоставляемый браузером.

  • При ошибочных настройках (например, выбран только неподдерживаемый кодек) в последних версиях софтфона реализован fallback: будет использован стандартный набор кодеков трансивера.

  • Для проверки соответствия используйте анализ SDP: приоритет в списках должен совпадать с тем, что выставлено в настройках. Номера (m= и a=rtpmap: строки) должны соответствовать тому порядку, в котором кодеки указаны в настройках пользователя.

  • Подробная инструкция и примеры диагностики описаны в разделе:
    Управление аудио / видео кодеками

6.5 Пример установки и проверки кодеков через API #

javascript
const audioCodecs = [
{ channels: 2, clockRate: 48000, mimeType: "audio/opus", sdpFmtpLine: "minptime=10;useinbandfec=1" },
{ channels: 2, clockRate: 48000, mimeType: "audio/red", sdpFmtpLine: "111/111" },
{ channels: 1, clockRate: 8000, mimeType: "audio/G722" }
];
OKTELLPhone.setCodecSettings({ audio: audioCodecs });

const supported = OKTELLPhone.getSupportedCodecs();
const current = OKTELLPhone.getCodecSettings();

  • После установки необходимо сверить список текущих и поддерживаемых кодеков через консоль разработчика, а также проконтролировать порядок и наличие их в SDP сообщения вызова.

Краткое резюме рекомендаций:

  • Применяйте фильтр кодеков только для исходящих вызовов.

  • Не исключайте все возможные кодеки — устанавливайте приоритет, а не жесткие ограничения.

  • Для успешных соединений используйте стандартные и совместимые кодеки (G.711, opus, VP8 и др).

  • Всегда тестируйте соединения между различными устройствами и браузерами на практике.

Это дополнение встроено в общий порядок руководства и должно использоваться совместно с официальной справкой по API и результатами внутренних тестов.

Оцените документ