Call manager SDK

SDK и серверная часть для осуществления звонков через Asterisk и WebRTC (аналог Twilio Voice SDK).

Термины

• SDK (software development kit) — библиотека для фронтенда, используется для звонков (аналог twilio-voice-sdk).
• Asterisk — решение компьютерной телефонии, обрабатывает SIP-звонки.
• WebRTC — технология передачи аудио/видео из браузера.
• API — интерфейс взаимодействия с веб-сервером (получение токенов, статусов, постбеков).

Принцип работы

1. Фронтенд подключает SDK.
2. При инициализации звонка:
   • SDK обращается к веб-серверу за токеном.
   • Сервер запрашивает у внешнего сервиса XML с данными для звонка.
   • Возвращает готовый объект с кредами.
3. SDK шифрует номер и инициирует соединение через SIP over WebSocket (JsSIP → Asterisk).
4. При успешном соединении начинается обмен медиа по WebRTC.
5. Веб-сервер отслеживает статусы звонка (accept, reject, busy, disconnect и т.д) и пушит их на фронтенд через сокеты.
6. После завершения звонка сервер рассылает постбеки (error, call_update, record).

SDK

Установка

npm install callmanager-voice-sdk

Использование

Основная работа происходит через 2 доступных класса - Device и Call. Для начала работы необходимо получить токен по роуту https://${BASE_PATH}/generate_token. Далее создаем инстанс Device - new Device(token, deviceParams) и передаем в него полученный токен, а также параметры для конструктора - здесь обязательны следующие поля:

• asteriskConnection - адрес сокета для подсоединения к Asterisk по Sip over Socket (пример - wss://asterisk.com)
• callManagerHttpConnection - адрес сервера для отправки http запросов (пример - https://server.com)
• callManagerWsConnection - адрес для подключения к серверу по сокету (пример - wss://server.com)

У созданного объекта появляется метод для звонка - connect(params), который принимает параметр типом Record<string, string> - в него передаем инфу для звонка. Метод SDK обратится к веб-серверу, получит актуальные данные для соединения, а также запросит xml, зашифрует полученный номер, чтобы он не светился в браузере, и вернет на SDK. Затем через JsSIP по sip over socket запрос пойдет на Asterisk, в случае успешного соединения начнется обмен медиа. Кроме того, поднимается сокет для отслеживания статусов звонка. Статусы отслеживаются на веб-сервере и оповещают об этом клиент. Вызванный метод connect() вернет объект Call, у которого через метод .on можно подписаться на события которые отрабатывают при изменении статуса.

Список доступных событий

• ringing - начало вызова, идет звонок
• accept - абонент принял звонок
• error - ошибка
• reject - звонок отклонен
• disconnect - завершение соединения (приходит после того как звонок был принят и завершен одной из сторон)
• cancel - отменен
• busy - абонент занят
• no_answer - нет ответа

Дополнительно

• метод destroy - доступен у инстанса Device, немедленно завершает звонок
• метод sendDigits - доступен у инстанса Call, принимает 2 параметра. Первый - тон в виде строки, второй объект опций (опционален)
• через Call.parameters можно получить CallSid текущего звонка. После завершения звонка подчищаются все открытые соединения и удаляются все ссылки на объекты

Пример использования

import { Device, Call } from "callmanager-voice-sdk";

// 1. Получаем токен
const token = await fetch("https://${BASE_PATH}/generate_token").then(r => r.text());

// 2. Создаем Device
const deviceParams = {
    asteriskConnection: 'wss://asterisk.com',
    callManagerHttpConnection: 'https://server.com',
    callManagerWsConnection: 'wss://server.com'
}
const device = new Device(token, deviceParams);

// 3. Инициируем звонок
const params = {
  manager_id: "1",
  trader_id: "01",
  outgoing_number: "+79000000000",
  encrypted_number: "secret_number"
};

const call = await device.connect(params);

// 4. Подписываемся на события
call.on("accept", (c: Call) => {
  console.log("Call accepted:", c.parameters.CallSid);
});

// 5. Передача тона
call.sendDigits('1', {duration: 1});

// 6. Разрыв соединения
device.destroy();

Веб-сервер

Выполняет функции:

• генерация и валидация токенов;
• выдача кредов;
• мониторинг состояния звонка;
• рассылка постбеков.

Постбеки рассылаются в несколько попыток после завершения звонка.

Генерация токенов

• Токены подписываются и проверяются через приватный и публичный ключи.
• Используемый алгоритм - RS256.
• При запросах токены приходят в заголовке 'X-Twilio-Signature'

Схема