Handleidingen

SIP

Wanneer de spraakagent en eenvoudig doorschakelen niet volstaan en u een nummer wilt koppelen aan uw eigen softphone of telefooncentrale (PBX), hebt u een SIP-trunkprovider nodig - volai is er een. Deze pagina is een stapsgewijze handleiding.

1Inkomende gesprekken naar uw SIP-server

Stel de routering van het nummer in op mode: "sip" en geef het uw sipUri - vandaar gaat het gesprek rechtstreeks naar u, niet naar onze agent of doorschakeling:

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

Alleen de inkomende minuut wordt gefactureerd - 0,50 kr/min (≈ 0,02 EUR), geen extra agent - de volledige vorm van het verzoek en de andere routeringsmodi staan in de REST API-referentie.

Authenticatie bij uw PBX

Wij sturen het gesprek eerst als niet-geauthenticeerde INVITE naar uw SIP-server op sipUri. Een PBX die daarop antwoordt met een inlog-uitdaging (401/407) en het gesprek zonder meer weigert, krijgt het in deze vorm nooit - er is niemand die de uitdaging beantwoordt. Voeg daarom ook sipUsername en sipPassword toe aan de routering - als u beide invult, beantwoordt ons netwerk de uitdaging (SIP digest) en belt het het gevraagde nummer. Geverifieerd met een live gesprek naar het native SIP-nummer van Vapi, dat gegevens accepteert ongeacht de inhoud. Of ook uw eigen PBX het gesprek verbindt, hangt van haar af - ze moet de INVITE echt met een uitdaging beantwoorden en de gebruikersnaam en het wachtwoord accepteren die u opgeeft; dat garanderen wij niet voor elke PBX (in tests mislukte het bijvoorbeeld tegen het SIP-domein van Twilio). Zonder sipUsername en sipPassword blijft de routering in de huidige niet-geauthenticeerde vorm. Zo voegt u de gegevens toe:

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

Het gevraagde nummer sturen wij altijd precies zoals het in sipUri vóór het @-teken staat - wij voegen nooit een prefix of voorloopnul toe en verwijderen er geen, dus de doel-PBX moet precies verwerken wat u daar invult.

Noch sipUsername noch sipPassword mag een dubbele punt, @-teken, witruimte, aanhalingsteken of backslash bevatten, en elk mag maximaal 64 tekens lang zijn.

Slechts één van de twee invullen wordt geweigerd - de API geeft terug "Please fill in both username and password, or leave both empty."

Een dubbele punt in het gebruikersdeel van sipUri (vóór het @-teken) en een poort in de host (na de dubbele punt achter de server, bijv. :5060) worden allebei nog niet ondersteund samen met sipUsername en sipPassword - beide geven dezelfde harde fout. Zonder gegevens blijven beide ongewijzigd werken.

Uitzondering: een Vapi BYO SIP-trunk (adres <credentialId>.sip.vapi.ai, of <credentialId>.sip.eu.vapi.ai voor een organisatie in de EU-regio) accepteert geen gegevens. Vapi herkent onze gesprekken aan het IP in de gateways van de trunk, en als sipUsername en sipPassword zijn ingevuld, wordt het gesprek nooit verbonden, dus de API weigert die routering met de validatiecode. Het native SIP-nummer van Vapi (sip:<name>@sip.vapi.ai) wordt hierdoor niet geraakt.

2SIP-gegevens voor een nummer

Haal de gegevens van de lijn op met één aanroep:

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

Instellen in een softphone (Zoiper, Linphone)

Beide apps vragen in wezen hetzelfde, alleen onder andere namen - zoek naar "Account toevoegen" / "SIP-account":

Na het opslaan hoort de softphone zich te registreren (een statuspictogram "online"/"geregistreerd") en gaan gesprekken naar het nummer rechtstreeks daarin overgaan.

3Uitgaande gesprekken vanuit een SIP-client

Zodra de softphone is geregistreerd, kan ze zelf via deze lijn uitbellen - daarvoor hoeft u geen van onze API's aan te roepen, u belt rechtstreeks vanuit de client zoals vanaf een gewone telefoonlijn.

4Limieten

• Eén registratie per lijn - één set gegevens ondersteunt op een bepaald moment één geregistreerd apparaat. Als u met een tweede client inlogt, verliest de eerste hoogstwaarschijnlijk zijn registratie - reken niet op meerdere apparaten tegelijk op één lijn.
• Uitgaand vanaf uw eigen agent ja, volledige trunk-peering nee - met de gegevens van de lijn registreert UW client zich bij ONS als telefoon. Uitgaande gesprekken vanaf uw eigen spraakagent (ElevenLabs of een ander platform) werken vandaag wél - via de relay, zie Breng uw eigen agent mee. U kunt uw PBX echter nog niet als peer-carrier met eigen routering koppelen voor INKOMENDE gesprekken van buiten - gebruik daarvoor forward routering naar het nummer van uw PBX.
• Alleen spraak - geen video of andere SIP-extensies.