Průvodci

SIP

Když ti nestačí hlasový agent ani jednoduché přesměrování a chceš si číslo připojit do vlastního softphonu nebo telefonní ústředny (PBX), potřebuješ SIP trunk poskytovatele - volai jím je. Tahle stránka je návod krok za krokem.

1Příchozí hovory na tvůj SIP server

Nastav směrování čísla na mode: "sip" a zadej svoji sipUri - odsud dál hovor putuje přímo k tobě, ne k naší nabídce agenta ani přesměrování:

curl -X PATCH "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "sip", "sipUri": "sip:recepce@tvuj-server.cz"}}'

Účtuje se jen příchozí minuta (0,50 Kč/min), žádný agent navíc - kompletní tvar požadavku i ostatní režimy směrování jsou v REST API referenci.

Ověření na tvé ústředně

Hovor na tvůj SIP server posíláme nejdřív jako neověřený INVITE na sipUri. Ústředna, která na něj odpoví výzvou k přihlášení (401/407) a bez dalších údajů hovor odmítne, ho v tomhle tvaru nedostane - výzvu totiž nemá kdo zvednout. Vyplň proto do směrování navíc sipUsername a sipPassword - vyplněním obou se naše síť na cíli přihlásí (SIP digest) a vytočí volané číslo. Ověřeno živým hovorem na nativní SIP číslo Vapi, které přihlašovací údaje přijme bez ohledu na jejich obsah. Jestli hovor spojí i tvoje ústředna, je na ní - musí na INVITE opravdu odpovědět výzvou a zadané jméno s heslem uznat; to negarantujeme pro každou ústřednu (v testu se to nepovedlo třeba proti SIP doméně Twilia). Bez sipUsername a sipPassword zůstává směrování v dnešním neověřeném tvaru. Přihlášení do směrování přidáš takhle:

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

Volané číslo posíláme vždy přesně v tom tvaru, v jakém je v sipUri před zavináčem - žádnou předvolbu ani nulu nepřidáváme ani neubíráme, takže se cílová ústředna musí umět vypořádat přesně s tím, co tam napíšeš.

sipUsername ani sipPassword nesmí obsahovat dvojtečku, zavináč, mezeru, uvozovku ani zpětné lomítko a smí mít nejvýš 64 znaků každé.

Vyplnit jen jedno z polí nejde - API vrátí chybu „Vyplň prosím jméno i heslo, nebo obojí nech prázdné.“.

Dvojtečka v uživatelské části sipUri (před zavináčem) ani port v hostu (za dvojtečkou u serveru, např. :5060) se s vyplněnými sipUsername a sipPassword zatím nepodporují - obojí vrací stejnou tvrdou chybu. Bez přihlašovacích údajů obojí funguje beze změny.

2SIP údaje čísla

Přihlašovací údaje linky si vyzvedneš jedním voláním:

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

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

Nastavení v softphonu (Zoiper, Linphone)

V obou appkách zadáváš v zásadě totéž, jen jinak pojmenované - hledej „Přidat účet“ / „SIP účet“:

Po uložení by se měl softphone zaregistrovat (stavová ikona „online“/„zaregistrováno“) a hovory na číslo začnou zvonit přímo v něm.

3Odchozí volání přes SIP klienta

Jakmile je softphone zaregistrovaný, může přes tuhle linku sám vytáčet ven - nemusíš kvůli tomu volat žádné naše API, vytáčíš přímo z klienta jako z obyčejné telefonní linky.

4Omezení

• Jedna registrace na linku - jedny přihlašovací údaje unesou jedno zaregistrované zařízení najednou. Když se přihlásíš druhým klientem, první o registraci nejspíš přijde - nespoléhej na víc zařízení současně na jedné lince.
• Odchozí z vlastního agenta ano, plné trunk peerování ne - přihlašovací údaje linky slouží k tomu, aby se TVŮJ klient zaregistroval k NÁM jako telefon. Odchozí hovory z vlastního hlasového agenta (ElevenLabs i jiná platforma) ale dnes JDOU - přes relay, viz Vlastní agent. Pořád ale nejde připojit tvoji ústřednu jako rovnocenného operátora s vlastním směrováním PŘÍCHOZÍCH hovorů zvenčí - na to použij směrování forward na číslo tvojí ústředny.
• Jen hlas - žádné video ani jiné SIP rozšíření.