Sprievodcovia

SIP

Keď vám nestačí hlasový agent ani jednoduché presmerovanie a chcete si číslo pripojiť do vlastného softfónu alebo telefónnej ústredne (PBX), potrebujete SIP trunk poskytovateľa - volai ním je. Táto stránka je návod krok za krokom.

1Prichádzajúce hovory na váš SIP server

Nastavte smerovanie čísla na mode: "sip" a zadajte svoju sipUri - odtiaľ hovor putuje priamo k vám, nie k našej ponuke agenta ani presmerovania:

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

Účtuje sa len prichádzajúca minúta (0,50 kr/min (≈ 0,02 EUR)), žiadny agent navyše - kompletný tvar požiadavky aj ostatné režimy smerovania sú v REST API referencii.

Overenie na vašej ústredni

Hovor na váš SIP server posielame najprv ako neoverený INVITE na sipUri. Ústredňa, ktorá naň odpovie výzvou na prihlásenie (401/407) a bez ďalších údajov hovor odmietne, ho v tomto tvare nedostane - výzvu totiž nemá kto zdvihnúť. Vyplňte preto do smerovania navyše sipUsername a sipPassword - vyplnením oboch sa naša sieť na cieli prihlási (SIP digest) a vytočí volané číslo. Overené živým hovorom na natívne SIP číslo Vapi, ktoré prihlasovacie údaje prijme bez ohľadu na ich obsah. Či hovor spojí aj vaša ústredňa, závisí od nej - musí na INVITE naozaj odpovedať výzvou a zadané meno s heslom uznať; to negarantujeme pre každú ústredňu (v teste sa to nepodarilo napríklad proti SIP doméne Twilia). Bez sipUsername a sipPassword ostáva smerovanie v dnešnom neoverenom tvare. Prihlásenie do smerovania pridáte takto:

curl -X PATCH "https://volai.eu/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_VAS_KLUC" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "sip", "sipUri": "sip:recepcia@vas-server.sk", "sipUsername": "recepcia", "sipPassword": "tajneheslo123"}}'

Volané číslo posielame vždy presne v tvare, v akom je v sipUri pred zavináčom - žiadnu predvoľbu ani nulu nepridávame ani neuberáme, takže sa cieľová ústredňa musí vedieť vyrovnať presne s tým, čo tam napíšete.

sipUsername ani sipPassword nesmú obsahovať dvojbodku, zavináč, medzeru, úvodzovku ani spätnú lomku a smú mať najviac 64 znakov každé.

Vyplniť len jedno z polí nejde - API vráti chybu „Please fill in both username and password, or leave both empty.“.

Dvojbodka v používateľskej časti sipUri (pred zavináčom) ani port v hoste (za dvojbodkou pri serveri, napr. :5060) sa s vyplnenými sipUsername a sipPassword zatiaľ nepodporujú - oboje vracia rovnakú tvrdú chybu. Bez prihlasovacích údajov oboje funguje bez zmeny.

Výnimka: BYO SIP trunk Vapi (adresa <credentialId>.sip.vapi.ai, pri organizácii v EÚ regióne <credentialId>.sip.eu.vapi.ai) prihlasovacie údaje nepoužíva. Vapi spozná naše hovory podľa IP v gateways trunku a s vyplnenými sipUsername a sipPassword by sa hovor nespojil, preto takéto smerovanie API odmietne s kódom validation. Natívneho SIP čísla Vapi (sip:<meno>@sip.vapi.ai) sa to netýka.

2SIP údaje čísla

Prihlasovacie údaje linky si vyzdvihnete jedným volaním:

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

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

Nastavenie v softfóne (Zoiper, Linphone)

V oboch appkách zadávate v zásade to isté, len inak pomenované - hľadajte „Pridať účet“ / „SIP účet“:

Po uložení by sa mal softfón zaregistrovať (stavová ikona „online“/„zaregistrované“) a hovory na číslo začnú zvoniť priamo v ňom.

3Odchádzajúce volanie cez SIP klienta

Hneď ako je softfón zaregistrovaný, môže cez túto linku sám vytáčať von - nemusíte kvôli tomu volať žiadne naše API, vytáčate priamo z klienta ako z obyčajnej telefónnej linky.

4Obmedzenia

• Jedna registrácia na linku - jedny prihlasovacie údaje unesú jedno zaregistrované zariadenie naraz. Keď sa prihlásite druhým klientom, prvý o registráciu pravdepodobne príde - nespoliehajte sa na viac zariadení súčasne na jednej linke.
• Odchádzajúce z vlastného agenta áno, plné trunk peerovanie nie - prihlasovacie údaje linky slúžia na to, aby sa VÁŠ klient zaregistroval k NÁM ako telefón. Odchádzajúce hovory z vlastného hlasového agenta (ElevenLabs aj iná platforma) však dnes IDÚ - cez relay, pozrite Vlastný agent. Stále však nejde pripojiť vašu ústredňu ako rovnocenného operátora s vlastným smerovaním PRICHÁDZAJÚCICH hovorov zvonka - na to použite smerovanie forward na číslo vašej ústredne.
• Len hlas - žiadne video ani iné SIP rozšírenia.