Web Voice SDK

Библиотека для работы с VoIP-телефонией в браузере, построенная на основе JsSIP.

🔥 Демо

Содержание

• Установка
• Основные возможности
• Быстрый старт
• Подробное руководство
  • Инициализация
  • Входящие звонки
  • Исходящие звонки
  • Управление звонком
  • Аудио устройства
  • DTMF и IVR
  • Обработка ошибок
• TypeScript
• Браузерная поддержка
• Ограничения
• Лицензия

Установка

npm install @exolve/web-voice-sdk
# или
yarn add @exolve/web-voice-sdk

Основные возможности

• 📞 Поддержка входящих и исходящих звонков
• 🔄 Управление несколькими линиями одновременно
• 🎚️ Управление аудио устройствами (микрофон/динамики)
• ⏸️ Постановка звонков на удержание
• 🔇 Управление микрофоном (mute/unmute)
• 📱 Отправка DTMF сигналов
• ↗️ Переадресация звонков
• 🔄 Автоматическое переподключение при обрыве связи
• 🔒 Поддержка WSS (защищенное соединение)
• 🌐 Настройка STUN/TURN серверов
• 📝 Полная TypeScript поддержка
• 🎯 События для всех состояний звонка

Быстрый старт

import { RegistrationEvent, Communicator } from 'web-voice-sdk';

// Создание коммуникатора
const communicator = new Communicator();

// Инициализация коммуникатора
communicator.initialize({
	debug: true,
});

// Получения клиента звонков
const callClient = communicator.callClient();

// Получение события регистрации аккаунта
callClient.on(RegistrationEvent.Registered, () => {
    console.debug('RegistrationEvent.Registered');
});

// Регистрация sip аккаунта
callClient.registerAccount(your_username, your_password);

// Позвонить по номеру
callClient.makeCall('number');

// Управление звонком
call.mute(); // Выключить микрофон
call.unmute(); // Включить микрофон
call.hold(); // Поставить на удержание
call.unhold(); // Снять с удержания
call.terminate(); // Завершить звонок
call.blindTransfer(number); // Перевод вызова по номеру
call.attendedTransfer(call2); // Перевод вызова с сопровождением

Подробное руководство

Инициализация

Создание экземпляра с полной конфигурацией:

// Создание коммуникатора
const communicator = new Communicator();


// Инициализация коммуникатора
communicator.initialize({
    enableSecureConnection: true, // Использовать WSS вместо WS
    // Настройки звонков
    maxLines: 3, // Максимальное количество линий
    debug: true, // Включить отладку

    // Включен ли рингтон для входящего звонка
    ringtoneEnabled?: boolean;
    // Путь до звука рингтона входящего звонка 
    ringtoneSound?: string;
});

События звонков

// Подписка на события звонков

callClient.on(CallEvent.New, (call: Call) => {
	// Появился новый звонок
});

callClient.on(CallEvent.Connected, (call: Call) => {
	// Соединение между двумя сторонами звонка установлено 
});

callClient.on(CallEvent.OnHold, (call: Call) => {
	// Звонок на удержании
});

callClient.on(CallEvent.Resumed, (call: Call) => {
	// Звонок снят с удержания
});

callClient.on(CallEvent.Error, (call: Call, error: CallError ) => {
	// Произошла ошибка звонка
    console.log(error);
});

callClient.on(CallEvent.Disconnected, (call: Call) => {
	// Звонок окончен
});

Входящие звонки

// Получение события о новом звонка
callClient.on(CallEvent.New, (call: Call) => {
    console.debug('CallEvent.New');
});

Исходящие звонки

// Позвонить по номеру
callClient.makeCall('number');

Управление звонком

// Базовое управление
call.mute(); // Выключить микрофон
call.unmute(); // Включить микрофон
call.hold(); // Поставить на удержание
call.unhold(); // Снять с удержания
call.terminate(); // Завершить звонок
call.blindTransfer(number); // Перевод вызова по номеру
call.attendedTransfer(call2); // Перевод вызова с сопровождением

Аудио устройства

API аудоустройств работает только при наличии активных звонков. Это сделано чтобы запрашивать доступ к микрофону у пользователя только при явном вызове. В случае вызова функций getAudioDevices, setAudioDevice без активных звонков возвращает событие AudioDeviceEvent.Error с AudioDeviceError.Type.NoActiveCalls.

// Получение списка аудио устройств
callClient.getAudioDevices().then(devices => {
    console.log(JSON.stringify(devices));
});
// Установка аудио устройств (динамика или микрофона)
callClient.setAudioDevice(device);
// Подписка на событие изменения списка аудио устройств
callClient.on( AudioDeviceEvent.Changed, (devices: AudioDevice[]) => {
    console.log(JSON.stringify(devices));
});

DTMF и IVR

call.sendDTMF("1");


// Пример работы с IVR меню
call.sendDTMF("1"); // "Нажмите 1 для соединения с оператором"
await new Promise(resolve => setTimeout(resolve, 2000));
call.sendDTMF("3"); // "Нажмите 3 для подтверждения"

TypeScript

Библиотека полностью типизирована. Основные типы:

/**
 * События регистрации клиента
 * @enum {string} RegistrationEvent
 * @property {string} NotRegistered - Клиент не зарегистрирован
 * @property {string} Registered - Клиент зарегистрирован
 * @property {string} Error - Ошибка регистрации
 */
enum RegistrationEvent {
    NotRegistered = 'not_registered',
    Registered = 'registered',
    Error = 'registration_error',
}

/**
 * Ошибки регистрации клиента
 */
namespace RegistrationError {
    /**
     * Ошибки регистрации клиента
     * @enum {string} Type - Тип ошибки
     * @property {string} ClientNotInitalized - Клиент не инициализирован.
     * @property {string} AuthorizationError - Ошибка авторизации
     * @property {string} ConnectionError - Ошибка подключения
     * @property {string} Other - Другая ошибка
     */
    enum Type {
        ClientNotInitalized = 'ClientNotInitalized',
        AuthorizationError = 'AuthorizationError',
        ConnectionError = 'ConnectionError',
        Other = 'Other',
    }
}

/**
 * Ошибка регистрации клиента
 * @interface RegistrationError
 * @property {RegistrationError.Type} type - Тип ошибки
 * @property {string} cause - Описание ошибки
 */
interface RegistrationError {
    type: RegistrationError.Type;
    cause: string;
}



/**
 * События вызова
 * @enum {string} CallEvent 
 * @property {string} New - Новый вызов
 * @property {string} Connected - Вызов подключен
 * @property {string} OnHold - Вызов на ожидании
 * @property {string} Resumed - Вызов возобновлен
 * @property {string} Error - Ошибка вызова
 * @property {string} Disconnected - Вызов разорван
 * @property {string} Mute - Вызов замьючен
 */
enum CallEvent {
    New = 'call_new',
    Connected = 'call_connected',
    OnHold = 'call_onhold',
    Resumed = 'call_resumed',
    Error = 'call_error',
    Disconnected = 'call_disconnected',
    Mute = 'call_mute_changed',
}


/**
 * Ошибки вызова
 */
namespace CallError {
    /**
     * Ошибки вызова
     * @enum {string} Type - типы ошибок
     * @property {string} NotActivated - Аккаунт не активирован
     * @property {string} NotFound - Вызов не найден
     * @property {string} AddressIncomplete - Неполный адрес
     * @property {string} AuthorizationFailed - Авторизация не удалась
     * @property {string} ConnectionFailed - Соединение не удалось
     * @property {string} MaxCallsReached - Достигнуто Максимальное количество вызовов
     * @property {string} MicrophoneError - Ошибка получения микрофона для звонка
     * @property {string} Other - Другая ошибка
     */
    export enum Type {
        NotActivated = 'NotActivated',
        NotFound = 'NotFound',
        AddressIncomplete = 'AddressIncomplete',
        AuthorizationFailed = 'AuthorizationFailed',
        ConnectionFailed = 'ConnectionFailed',
        MaxCallsReached = 'MaxCallsReached',
        MicrophoneError = 'MicrophoneError',
        Other = 'Other',
    }
}

/**
 * Ошибка вызова
 * @interface CallError
 * @property {CallError.Type} type - Тип ошибки
 * @property {string} cause - Описание ошибки
 * @property {string} originator - Сторона инициации ошибки
 */
interface CallError {
    type: CallError.Type;
    cause: string;
    originator: string;
}

/**
 * Ошибки аудиоустройств
 */
namespace AudioDeviceError {
    /**
     * Ошибки аудиоустройств
     * @enum {string} Type - типы ошибок
     * @property {string} BrowserNotSupportSelectSpeaker - Браузер не поддерживает выбор динамика
     * @property {string} BrowserMediaDevicesNotSupported - Браузер не поддерживает MediaDevices API
     * @property {string} NoActiveCalls - Нет активных вызовов
     * @property {string} NotFound - Устройство не найдено
     * @property {string} SetSink - Ошибка установки динамика
     * @property {string} Other - Другая ошибка
     */
    enum Type {
        BrowserNotSupportSelectSpeaker = 'BrowserNotSupportSelectSpeaker',
        BrowserMediaDevicesNotSupported = 'BrowserMediaDevicesNotSupported',
        NoActiveCalls = 'NoActiveCalls',
        NotFound = 'NotFound',
        SetSink = 'SetSink',
        Other = 'Other'
    }
}

/**
 * Ошибки аудиоустройств
 * @interface AudioDeviceError
 * @property {AudioDeviceError.Type} type - Тип ошибки
 * @property {string} cause - Описание ошибки
 */
export interface AudioDeviceError {
    type: AudioDeviceError.Type;
    cause: string;
}


/**
 * Конфигурация для создания SIP-клиента
 */
type Configuration = {
    /** Включить режим отладки */
    debug?: boolean;
    /** Использовать защищенное соединение (WSS вместо WS) */
    enableSecureConnection?: boolean;
    /** Максимальное количество линий */
    maxLines?: number;
    /** Включен ли рингтон для входящего звонка */
    ringtoneEnabled?: boolean;
    /** Звук рингтона входящего звонка */
    ringtoneSound?: string;
};

Браузерная поддержка

Библиотека работает во всех современных браузерах, поддерживающих WebRTC:

• Chrome/Chromium (Desktop & Android)
• Firefox (Desktop & Android)
• Safari (Desktop & iOS)
• Edge (Chromium-based)

Особенности браузеров

Chrome

• Полная поддержка всех функций
• Лучшая производительность WebRTC
• Поддержка выбора аудио устройств

Firefox

• Хорошая поддержка WebRTC
• Могут быть проблемы с некоторыми STUN/TURN серверами
• Ограниченная поддержка выбора динамиков

Safari

• Базовая поддержка WebRTC
• Проблемы с удержанием звонков
• Нет поддержки выбора динамиков
• Требуется явное разрешение на доступ к медиа

Edge

• Аналогично Chrome (использует Chromium)
• Полная поддержка всех функций

Ограничения

1. Аудио устройства:

   • Выбор динамика работает только в Chrome и Edge
   • Требуется HTTPS для доступа к медиа устройствам
   • Необходимо разрешение пользователя

2. WebRTC:

   • Требуется поддержка браузером
   • Может блокироваться файрволами
   • Нужны STUN/TURN серверы для работы через NAT

3. Сеть:

   • Требуется стабильное соединение
   • WebSocket должен быть доступен
   • Порты для WebRTC должны быть открыты

4. Safari:

   • Ограниченная поддержка WebRTC
   • Проблемы с удержанием
   • Особые требования к медиа

Лицензия

MIT