Свой SIP (Custom)
Подключение собственной АТС / SIP-trunk к Voxagent — настройка на стороне PBX и на стороне платформы
Voxagent поддерживает подключение любой SIP-телефонии — собственной АТС (Mango Office, Asterisk, FreeSWITCH, виртуальной АТС у провайдера) — по стандартному SIP-протоколу. Это альтернатива готовым интеграциям с Twilio и VoxImplant для тех, у кого уже есть свой SIP-trunk.
Архитектура подключения
В Custom SIP участвуют две стороны, у каждой свои настройки. Чтобы звонки пошли в обе стороны, нужно сконфигурировать обе.
| Сторона | За что отвечает |
|---|---|
| Ваша АТС / SIP-провайдер | Терминирует звонок с PSTN (телефонная сеть), маршрутизирует входящие к нам, принимает наши исходящие |
| Voxagent (LiveKit SIP) | Принимает входящие INVITE от вашей АТС, инициирует исходящие звонки к ней, запускает AI-агента в LiveKit-комнате |
PSTN ──► Ваша АТС ──SIP INVITE──► LiveKit SIP gateway ──► AI-агент (LiveKit room)
PSTN ◄── Ваша АТС ◄──SIP INVITE── LiveKit SIP gateway ◄── AI-агент (исходящий)LiveKit как SIP-узел
LiveKit-сервер платформы включает встроенный SIP-компонент, который работает как обычный SIP-trunk: принимает INVITE, аутентифицирует, маршрутизирует в LiveKit-комнату с агентом, и наоборот — инициирует исходящий INVITE от своего имени.
Что настраиваем на стороне платформы
В Voxagent создаётся Custom SIP аккаунт — связка параметров вашего PBX. После создания платформа отдаёт публичные данные LiveKit (домен шлюза и наши исходящие IP), которые вы передаёте на сторону АТС.
Создать аккаунт
- Перейдите в Phone Numbers в https://console.voxagent.ru
- Нажмите Import number → From Custom SIP
- В дравере нажмите Добавить SIP-аккаунт
- Заполните форму:
| Поле | Что вводить | Пример |
|---|---|---|
| Имя аккаунта | Любое читаемое название | Mango Office |
| Адрес SIP-сервера | host[:port] SIP-сервера вашей АТС (для исходящих от нас). Пусто = исходящие отключены | vpbx400312852.mangosip.ru |
| SIP transport | Транспортный протокол: Auto / UDP / TCP / TLS. Auto — пусть LiveKit выберет сам | Auto |
| Страна назначения | ISO-3166 α-2 (2 буквы). Hint для биллинга/маршрутизации LiveKit, не ограничение по направлению звонка | RU |
| Разрешённые входящие IP | Список IPv4 / IPv4-CIDR через запятую — IP вашей АТС, с которых LiveKit будет принимать INVITE | 1.2.3.4, 10.0.0.0/24 |
| Outbound SIP логин/пароль | Опционально. Если задано — мы аутентифицируемся у вашей АТС через Digest-auth. Если пусто — IP-trust (АТС доверяет нашим IP) | livekit-out / *** |
| Inbound SIP логин/пароль | Опционально. Если задано — LiveKit потребует Digest-auth от вашей АТС на входящих. Большинство провайдеров входящие не challenge'ят — оставляйте пустым | пусто |
Получить публичные параметры платформы
После успешного создания аккаунта в карточке отобразятся:
- Domain — публичный домен LiveKit SIP-шлюза, например
livekit-sip.speaknode.com:5060. Это куда ваша АТС будет отправлятьINVITEдля входящих. - Our SIP server IPs — список наших исходящих IP, например
78.47.123.164:5060. Эти IP надо добавить в whitelist вашего firewall'а, чтобы АТС принимала наши исходящие звонки.
Эти данные нужно передать администратору АТС — без них вторая сторона не настроится.
Привязать номер
После настройки обеих сторон номер можно привязать к агенту:
- В Phone Numbers → Import number → From Custom SIP
- Выберите созданный SIP-аккаунт
- Введите номер в формате E.164 (например,
+71234567890) - (опционально) добавьте метку
- Нажмите Connect
После привязки можно зайти в карточку номера и назначить агента, который будет обрабатывать входящие звонки на этот номер.
Что настраиваем на стороне АТС
На стороне вашей SIP-АТС (Mango, Asterisk и т.д.) нужно настроить трёх вещи: куда отправлять входящие, кого пускать на исходящие, и аутентификацию (если используется).
Маршрут исходящих от АТС в LiveKit (наши входящие)
Для входящих звонков из PSTN через вашу АТС к агенту настройте маршрут к нашему SIP-шлюзу:
- Destination / Outbound trunk URI: домен LiveKit SIP-шлюза из карточки аккаунта в Voxagent — например,
sip:livekit-sip.speaknode.com:5060 - Transport: совпадает с тем, что задано в Custom SIP-аккаунте (
UDP/TCP/TLSлибоAuto) - Аутентификация (если включена Inbound auth): логин/пароль из формы Custom SIP-аккаунта
Конкретные шаги зависят от вашего вендора:
- Mango Office — SIP-trunk → раздел «Маршрутизация» → создать правило с destination на наш домен
- Asterisk — добавить
extensionвextensions.confсDial(SIP/livekit-sip.speaknode.com)через настроенный[livekit]SIP-peer - Виртуальная АТС другого провайдера — поищите раздел «Исходящие маршруты» / «Outbound routing» / «SIP trunk»
Whitelist наших IP (наши исходящие)
Если ваша АТС за firewall'ом, добавьте наши исходящие IP (Our SIP server IPs из карточки) в whitelist — без этого ваш сервер будет резать наши INVITE-пакеты на исходящих звонках от агента.
В зависимости от провайдера:
- Корпоративный firewall — добавить IP в правила
- Cloud-PBX (Mango и т.д.) — IP-whitelist в личном кабинете
- Asterisk + iptables —
iptables -A INPUT -s <ip> -p udp --dport 5060 -j ACCEPT
Outbound аутентификация (если включена)
Если вы задали Outbound SIP логин/пароль в нашем аккаунте — на стороне АТС создайте SIP-аккаунт с теми же креденшелами, который LiveKit будет использовать для аутентификации при инициации исходящих.
Если пусто — режим IP-trust: АТС просто доверяет нашим IP без логина/пароля. Это типично для Mango SIP-trunk, Plivo и других провайдеров с IP-allowlist.
Режимы аутентификации
В Custom SIP-аккаунте независимо настраиваются два направления — outbound и inbound. Для каждого можно выбрать один из двух режимов:
| Режим | Когда использовать | Что делать |
|---|---|---|
| Digest auth | Провайдер требует SIP-аутентификацию по логину/паролю | Задать оба поля (логин + пароль) |
| IP-trust | Провайдер пускает по IP-allowlist без аутентификации (Mango SIP-trunk, Plivo и т.д.) | Оставить оба поля пустыми |
Парная инвариантность
Логин и пароль всегда задаются вместе или оба остаются пустыми. Один из двух заполнить нельзя — UI отвергнет такую комбинацию.
При редактировании аккаунта поле «Пароль» имеет три состояния:
- Не трогали — текущий пароль остаётся
- Явно очищено — auth отключается (логин тоже очистите)
- Введено новое значение — пароль перезаписывается
Verify и Reprovision
В карточке Custom SIP-аккаунта доступны две диагностические операции:
Verify
Кнопка Verify запускает health-check и показывает 4 проверки:
| Проверка | Что означает |
|---|---|
| Local config | Аккаунт корректно сконфигурирован в БД (есть все обязательные поля) |
| Inbound trunk | LiveKit видит inbound SIP-trunk, готов принимать входящие |
| Outbound trunk | LiveKit видит outbound SIP-trunk, готов инициировать исходящие |
| Numbers in sync | Привязанные номера синхронизированы с LiveKit |
Каждая проверка может быть OK / Failed / Skipped. При Failed в reason'е указана причина.
Reprovision
Кнопка Reprovision удаляет и пересоздаёт LiveKit-trunki из текущей конфигурации БД. Используется в двух случаях:
- После изменения креденшелов / сервера / транспорта в карточке аккаунта (изменения автоматически реинициализируют trunks; reprovision — на случай если автоматика не сработала)
- Если LiveKit был недоступен при первом создании или привязке номера и trunks не создались (HTTP 500 на bind / create)
Reprovision и активные звонки
Reprovision удаляет старые trunks. Если в этот момент идут активные звонки через них — они прервутся. Запускайте reprovision вне пиковых часов или когда нет активных сессий.
Удаление аккаунта
При удалении Custom SIP-аккаунта (кнопка Delete в карточке) платформа:
- Удаляет все привязанные номера
- Удаляет LiveKit inbound / outbound trunks
- Soft-delete аккаунта в БД
После удаления на стороне АТС останутся ваши настройки маршрутизации к нашему шлюзу — их при необходимости удалите вручную в личном кабинете провайдера.
Частые проблемы
| Симптом | Причина | Решение |
|---|---|---|
Verify → Inbound trunk: Failed | LiveKit не создал inbound trunk (был недоступен на create) | Reprovision |
Verify → Numbers in sync: Failed | Расхождение БД ↔ LiveKit (например, после ручной правки в LiveKit) | Reprovision |
| Входящие не доходят до агента | Неправильный destination на АТС, или наш IP не в whitelist | Проверьте Domain в карточке и IP-allowlist на АТС |
| Исходящие падают с 403 / 407 | Outbound auth не совпадает | Проверьте Outbound логин/пароль в карточке и SIP-аккаунт на АТС |
| Исходящие падают с timeout | Наши IP не в whitelist firewall'а на стороне АТС | Добавьте Our SIP server IPs в whitelist |
409 при привязке номера | Номер уже привязан к другому Custom SIP аккаунту (включая другой Space) | Используйте другой номер либо удалите предыдущую привязку |