Vejledninger

SIP

Når stemmeagenten og simpel viderestilling ikke er nok, og nummeret skal forbindes til en egen softphone eller telefoncentral (PBX), er en SIP-trunk-udbyder nødvendig - volai er en sådan. Denne side er en trin-for-trin-vejledning.

1Indgående opkald til en egen SIP-server

Sæt nummerets routing til mode: "sip" og angiv den egen sipUri - herfra går opkaldet direkte til modtageren, ikke til vores agenttilbud eller viderestilling:

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

Kun det indgående minut afregnes (0,50 kr/min (≈ 0,16 DKK)), ingen ekstra agent - den fulde form af forespørgslen og de øvrige routingtilstande findes i REST API-referencen.

Godkendelse på telefoncentralen

Opkaldet til den egen SIP-server sendes først som en ugodkendt INVITE til sipUri. En central, der svarer med en login-udfordring (401/407) og afviser opkaldet uden yderligere oplysninger, får det ikke i denne form - der er ingen, der kan besvare udfordringen. Udfyld derfor i routingen desuden sipUsername og sipPassword - når begge er udfyldt, logger vores netværk ind på målet (SIP digest) og ringer til det kaldte nummer. Kontrolleret med et live-opkald til Vapis native SIP-nummer, som accepterer oplysninger uanset indholdet. Om den egen central også forbinder opkaldet, afhænger af den - den skal faktisk besvare INVITE med en udfordring og godkende det angivne brugernavn og kodeord; det garanteres ikke for alle centraler (i testen mislykkedes det for eksempel mod Twilios SIP-domæne). Uden sipUsername og sipPassword forbliver routingen i den nuværende ugodkendte form. Login tilføjes til routingen sådan:

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

Det kaldte nummer sendes altid præcis i den form, det har i sipUri før snabel-a - der tilføjes eller fjernes hverken forvalg eller nul, så målcentralen skal kunne håndtere præcis det, der står dér.

Hverken sipUsername eller sipPassword må indeholde kolon, snabel-a, mellemrum, citationstegn eller omvendt skråstreg, og hver må højst være 64 tegn.

Det er ikke muligt at udfylde kun det ene af felterne - API'et returnerer fejlen "Please fill in both username and password, or leave both empty."

Et kolon i brugerdelen af sipUri (før snabel-a) og en port i hosten (efter kolon ved serveren, f.eks. :5060) understøttes endnu ikke sammen med udfyldt sipUsername og sipPassword - begge giver den samme hårde fejl. Uden login-oplysninger fungerer begge uændret.

Undtagelse: en BYO SIP-trunk hos Vapi (adresse <credentialId>.sip.vapi.ai, for en organisation i EU-regionen <credentialId>.sip.eu.vapi.ai) bruger ikke login-oplysninger. Vapi genkender vores opkald på IP-adressen i trunkens gateways, og med udfyldt sipUsername og sipPassword ville opkaldet ikke blive forbundet, så API'et afviser en sådan routing med koden validation. Vapis native SIP-nummer (sip:<navn>@sip.vapi.ai) er ikke berørt.

2SIP-oplysninger for nummeret

Linjens login-oplysninger hentes med ét kald:

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

Opsætning i en softphone (Zoiper, Linphone)

Begge apps beder i princippet om det samme, blot med andre navne - led efter "Tilføj konto" / "SIP-konto":

Efter gemning bør softphonen registrere sig (statusikon "online"/"registreret"), og opkald til nummeret begynder at ringe direkte i den.

3Udgående opkald via en SIP-klient

Så snart softphonen er registreret, kan den selv ringe ud via denne linje - der skal ikke kaldes noget af vores API til det, der ringes direkte fra klienten som fra en almindelig telefonlinje.

4Begrænsninger

• Én registrering pr. linje - ét sæt login-oplysninger understøtter én registreret enhed ad gangen. Hvis der logges ind med en anden klient, mister den første sandsynligvis sin registrering - stol ikke på flere enheder samtidig på én linje.
• Udgående fra en egen agent ja, fuld trunk-peering nej - linjens login-oplysninger tjener til, at EN KLIENT registrerer sig hos OS som telefon. Udgående opkald fra en egen stemmeagent (ElevenLabs eller en anden platform) KAN dog i dag lade sig gøre - via relay, se Egen agent. Det er stadig ikke muligt at forbinde en central som ligeværdig operatør med egen routing af INDGÅENDE opkald udefra - brug til det routingen forward til centralens nummer.
• Kun tale - ingen video eller andre SIP-udvidelser.