Ръководства

SIP

Когато гласовият агент и простото пренасочване не Ви стигат и искате да свържете номера със собствен софтфон или телефонна централа (PBX), Ви трябва доставчик на SIP trunk - volai е такъв. Тази страница е ръководство стъпка по стъпка.

1Входящи обаждания към Вашия SIP сървър

Задайте маршрутизирането на номера на mode: "sip" и въведете своя sipUri - оттам нататък обаждането отива директно при Вас, а не към нашия агент или пренасочване:

curl -X PATCH "https://volai.eu/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "sip", "sipUri": "sip:reception@your-server.com"}}'

Таксува се само входящата минута (0,50 kr/min (≈ 0,02 EUR)), без допълнителен агент - пълният вид на заявката и останалите режими на маршрутизиране са в референцията на REST API.

Удостоверяване на Вашата централа

Обаждането към Вашия SIP сървър първо го изпращаме като неудостоверен INVITE към sipUri. Централа, която отговаря на него с покана за вход (401/407) и без допълнителни данни отхвърля обаждането, в този вид няма да го получи - поканата няма кой да я приеме. Затова попълнете в маршрутизирането допълнително sipUsername и sipPassword - след попълването на двете нашата мрежа се удостоверява на целта (SIP digest) и набира търсения номер. Проверено с реално обаждане към роден SIP номер на Vapi, който приема данните за вход независимо от съдържанието им. Дали обаждането ще свърже и Вашата централа, зависи от нея - тя трябва наистина да отговори на INVITE с покана и да признае зададеното име и парола; това не гарантираме за всяка централа (в тест не се получи например срещу SIP домейн на Twilio). Без sipUsername и sipPassword маршрутизирането остава в днешния неудостоверен вид. Удостоверяването се добавя към маршрутизирането така:

curl -X PATCH "https://volai.eu/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "sip", "sipUri": "sip:reception@your-server.com", "sipUsername": "reception", "sipPassword": "supersecret123"}}'

Търсения номер винаги изпращаме точно във вида, в който е в sipUri преди знака @ - не добавяме, нито махаме префикс или нула, затова целевата централа трябва да се справя точно с това, което пишете там.

sipUsername и sipPassword не могат да съдържат двоеточие, @, интервал, кавичка или обратна наклонена черта и могат да имат най-много по 64 знака.

Попълването само на едно от двете полета не е възможно - API връща грешката "Please fill in both username and password, or leave both empty."

Двоеточие в потребителската част на sipUri (преди @) и порт в хоста (след двоеточие при сървъра, напр. :5060) при попълнени sipUsername и sipPassword засега не се поддържат - и двете връщат една и съща твърда грешка. Без данни за вход и двете работят без промяна.

Изключение: BYO SIP trunk на Vapi (адрес <credentialId>.sip.vapi.ai, при организация в региона ЕС <credentialId>.sip.eu.vapi.ai) не използва данни за вход. Vapi разпознава нашите обаждания по IP адреса в gateways на trunk-а и при попълнени sipUsername и sipPassword обаждането няма да се свърже, затова API отхвърля такова маршрутизиране с код validation. Това не се отнася за роден SIP номер на Vapi (sip:<име>@sip.vapi.ai).

2SIP данни на номера

Данните за вход на линията вземате с едно извикване:

curl "https://volai.eu/v1/numbers/+420601234567/sip" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "server": "sip.volai.cz",
  "username": "123456",
  "password": "a1b2c3d4e5f6",
  "outboundTrunkAddress": "sip.volai.cz",
  "port": 5060,
  "transport": "tcp",
  "inboundSignallingCidrs": ["81.31.45.0/24"]
}

Настройка в софтфон (Zoiper, Linphone)

И в двете приложения въвеждате по принцип едно и също, само че с различни имена - търсете „Добавяне на акаунт“ / „SIP акаунт“:

След запазването софтфонът трябва да се регистрира (иконата за състояние „онлайн“/„регистриран“) и обажданията към номера ще започнат да звънят директно в него.

3Изходящи обаждания през SIP клиент

Щом софтфонът е регистриран, той може сам да набира навън през тази линия - не е нужно за това да извиквате наше API, набирате директно от клиента като от обикновена телефонна линия.

4Ограничения

• Една регистрация на линия - едни данни за вход издържат едно регистрирано устройство наведнъж. Ако се впишете с втори клиент, първият най-вероятно губи регистрацията си - не разчитайте на няколко устройства едновременно на една линия.
• Изходящи от собствен агент - да, пълно trunk peering - не - данните за вход на линията служат за това ВАШИЯТ клиент да се регистрира при НАС като телефон. Изходящите обаждания от собствен гласов агент (ElevenLabs или друга платформа) обаче днес СА възможни - през relay, вижте Собствен агент. Все още обаче не може да свържете Вашата централа като равноправен оператор със собствено маршрутизиране на ВХОДЯЩИ обаждания отвън - за това използвайте маршрутизиране forward към номера на Вашата централа.
• Само глас - без видео и други SIP разширения.