Руководство по архитектуре Voice API

Voice API управляются событиями: платформа обращается к вам по мере развития звонка.

• Разберитесь в событиях жизненного цикла звонка (инициирован, звонит, отвечен, завершён), которые генерирует ваш API.Ваш обработчик webhook по сути является машиной состояний потока звонка — проектируйте его именно так.
• Моделируйте управление вызовами как идемпотентные обработчики webhook, устойчивые к повторам и событиям вне порядка.
• Выбирайте между декларативными документами потока звонка и живым управлением через API для каждого сценария использования.
• Учитывайте неизбежные концепции SIP: раннее медиа (early media), DTMF, перевод звонка и семантику re-INVITE.
• Спланируйте стратегию номеров (E.164), отображение caller ID и правила отображения caller ID по рынкам.

• Выбирайте кодеки осознанно: G.711 для качества, G.729/Opus там, где полоса пропускания ограничена.Закладывайте бюджет полосы пропускания, включая накладные расходы IP/UDP/RTP, а не только битрейт кодека.
• Установите разумный интервал пакетизации (обычно 20 мс), балансируя накладные расходы и задержку.
• Проектируйте с учётом джиттера, потери пакетов и задержки: буферы джиттера и реалистичные ожидания по MOS.
• Спланируйте обработку DTMF (RFC 2833 / SIP INFO / в полосе) единообразно на всём пути.
• Определите потребности в записи и транскрибации заранее — они влияют на маршрутизацию медиа и хранение.

• Проверяйте подписи webhook и отклоняйте неподписанные или устаревшие события.Неаутентифицированный webhook управления вызовом — это риск перехвата.
• Отвечайте на webhook быстро и выполняйте тяжёлую работу асинхронно, чтобы не блокировать звонок.
• Делайте обработчики идемпотентными и дедуплицируйте по идентификаторам событий, поскольку повторы ожидаемы.
• Сопоставляйте плечи звонка (call legs) по стабильному идентификатору звонка/сессии через перевод и конференцию.

• Рассчитывайте число одновременных каналов из CPS × средняя длительность звонка, затем добавляйте пиковый запас.Одновременные звонки ≈ звонков в секунду × средняя длительность в секундах.
• Обеспечивайте ёмкость транка / каналов и подтверждайте лимиты параллельности и CPS у провайдера.
• Масштабируйте обработчики webhook горизонтально и держите их без состояния за очередью.
• Проводите нагрузочное тестирование на пиковой параллельности и подтверждайте плавную деградацию, а не отказ по обрыву.

• Шифруйте сигнализацию (SIP поверх TLS) и медиа (SRTP) там, где это предлагается; ограничивайте доступ по списку разрешённых IP.
• Защищайтесь от телефонного мошенничества и Wangiri: ограничивайте по скорости и ограничивайте доступ к высокорисковым премиум-направлениям.
• Проектируйте failover между регионами/провайдерами, чтобы единичный сбой не обрывал все звонки.
• Ведите подробные записи по каждому звонку (CDR) и события и храните аудио только в соответствии с вашими требованиями по соответствию.
• Инструментируйте метрики качества (MOS, ASR, ACD) и формируйте оповещения о падениях по маршрутам.