Przewodniki

SIP

Gdy agent głosowy i proste przekierowanie nie wystarczają, a chcą Państwo podłączyć numer do własnego softphone'a lub centrali telefonicznej (PBX), potrzebny jest dostawca SIP trunk - volai nim jest. Ta strona to przewodnik krok po kroku.

1Połączenia przychodzące na Państwa serwer SIP

Proszę ustawić routing numeru na mode: "sip" i podać swój sipUri - stąd połączenie trafia bezpośrednio do Państwa, a nie do naszego agenta ani przekierowania:

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"}}'

Rozliczana jest tylko minuta połączenia przychodzącego (0,50 kr/min (≈ 0,09 PLN)), bez dodatkowego agenta - pełny kształt żądania i pozostałe tryby routingu opisuje referencja REST API.

Uwierzytelnianie na Państwa centrali

Połączenie na Państwa serwer SIP wysyłamy najpierw jako nieuwierzytelnione INVITE na sipUri. Centrala, która odpowie na nie wezwaniem do zalogowania (401/407) i bez dodatkowych danych odrzuci połączenie, w tej postaci go nie otrzyma - wezwania nie ma kto odebrać. Proszę więc dodatkowo uzupełnić w routingu sipUsername i sipPassword - po uzupełnieniu obu pól nasza sieć zaloguje się na docelowej centrali (SIP digest) i wybierze numer docelowy. Zweryfikowano rzeczywistym połączeniem na natywny numer SIP Vapi, który przyjmuje dane logowania niezależnie od ich zawartości. To, czy Państwa centrala również połączy rozmowę, zależy od niej - musi rzeczywiście odpowiedzieć na INVITE wezwaniem i uznać podaną nazwę z hasłem; nie gwarantujemy tego dla każdej centrali (w teście nie udało się to na przykład wobec domeny SIP Twilio). Bez sipUsername i sipPassword routing pozostaje w dzisiejszej, nieuwierzytelnionej postaci. Logowanie dodaje się do routingu tak:

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"}}'

Numer wywoływany wysyłamy zawsze dokładnie w takiej postaci, w jakiej stoi w sipUri przed znakiem @ - nie dodajemy ani nie odejmujemy żadnego prefiksu ani zera, więc centrala docelowa musi poradzić sobie dokładnie z tym, co Państwo tam wpiszą.

sipUsername ani sipPassword nie mogą zawierać dwukropka, znaku @, spacji, cudzysłowu ani odwrotnego ukośnika i mogą mieć najwyżej 64 znaki każde.

Uzupełnienie tylko jednego z pól nie jest możliwe - API zwraca komunikat po angielsku: "Please fill in both username and password, or leave both empty."

Dwukropek w części użytkownika sipUri (przed znakiem @) ani port w hoście (po dwukropku przy serwerze, np. :5060) nie są na razie obsługiwane przy uzupełnionych sipUsername i sipPassword - oba zwracają ten sam twardy błąd. Bez danych logowania oba działają bez zmian.

Wyjątek: BYO SIP trunk Vapi (adres <credentialId>.sip.vapi.ai, dla organizacji w regionie UE <credentialId>.sip.eu.vapi.ai) nie używa danych logowania. Vapi rozpoznaje nasze połączenia po IP w gateways trunku, a przy uzupełnionych sipUsername i sipPassword połączenie nie zostałoby nawiązane, dlatego API odrzuca taki routing z kodem validation. Natywnego numeru SIP Vapi (sip:<nazwa>@sip.vapi.ai) to nie dotyczy.

2Dane SIP numeru

Dane logowania linii można pobrać jednym wywołaniem:

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"]
}

Konfiguracja w softphone (Zoiper, Linphone)

W obu aplikacjach wpisuje się w zasadzie to samo, tylko inaczej nazwane - proszę szukać „Dodaj konto” / „Konto SIP”:

Po zapisaniu softphone powinien się zarejestrować (ikona stanu „online”/„zarejestrowany”), a połączenia na numer zaczną dzwonić bezpośrednio w nim.

3Połączenia wychodzące przez klienta SIP

Gdy softphone jest zarejestrowany, może sam wybierać numery przez tę linię - nie trzeba w tym celu wywoływać żadnego naszego API, wybiera się numer bezpośrednio z klienta jak ze zwykłej linii telefonicznej.

4Ograniczenia

• Jedna rejestracja na linię - jedne dane logowania obsługują jedno zarejestrowane urządzenie naraz. Gdy zalogują się Państwo drugim klientem, pierwszy najprawdopodobniej straci rejestrację - proszę nie polegać na kilku urządzeniach jednocześnie na jednej linii.
• Wychodzące z własnego agenta tak, pełny peering trunk nie - dane logowania linii służą temu, aby PAŃSTWA klient zarejestrował się u NAS jako telefon. Połączenia wychodzące z własnego agenta głosowego (ElevenLabs i innej platformy) jednak dziś DZIAŁAJĄ - przez relay, patrz Własny agent. Nadal nie można jednak podłączyć Państwa centrali jako równorzędnego operatora z własnym routingiem połączeń PRZYCHODZĄCYCH z zewnątrz - do tego proszę użyć routingu forward na numer Państwa centrali.
• Tylko głos - bez wideo ani innych rozszerzeń SIP.