Guides

SIP

When the voice agent and simple forwarding aren't enough and you want to connect a number to your own softphone or phone system (PBX), you need a SIP trunk provider - volai is one. This page is a step-by-step guide.

1Inbound calls to your SIP server

Set the number's routing to mode: "sip" and give it your sipUri - from there the call goes straight to you, not to our agent or forwarding:

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

Only the inbound minute is billed - 0.50 CZK/min (~EUR 0.02), no extra agent - the full request shape and the other routing modes are in the REST API reference.

Authentication with your PBX

We first send the call to your SIP server as an unauthenticated INVITE to sipUri. A PBX that answers it with a login challenge (401/407) and refuses the call without more never gets it in this shape - there's no one to answer the challenge. So add sipUsername and sipPassword to the routing as well - filling in both makes our network answer the challenge (SIP digest) and dial the called number. Verified with a live call to Vapi's native SIP number, which accepts credentials regardless of their content. Whether your own PBX also connects the call is up to it - it has to actually answer the INVITE with a challenge and accept the username and password you give it; we don't guarantee that for every PBX (in testing it failed, for example, against Twilio's SIP domain). Without sipUsername and sipPassword, routing stays in today's unauthenticated form. Add the credentials like this:

curl -X PATCH "https://volai.cz/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"}}'

We always send the called number exactly as it appears in sipUri before the @ sign - we never add or strip a prefix or a leading zero, so the target PBX has to handle exactly what you put there.

Neither sipUsername nor sipPassword may contain a colon, @ sign, whitespace, quote or backslash, and each can be at most 64 characters.

Filling in just one of the two is rejected - the API returns "Please fill in both username and password, or leave both empty."

A colon in the user part of sipUri (before the @ sign) and a port in the host (after the colon following the server, e.g. :5060) are both not yet supported together with sipUsername and sipPassword - both return the same hard error. Both keep working unchanged without credentials.

2SIP credentials for a number

Fetch the line's credentials with a single call:

curl "https://volai.cz/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"]
}

Setup in a softphone (Zoiper, Linphone)

Both apps ask for essentially the same thing, just under different names - look for "Add account" / "SIP account":

After saving, the softphone should register (an "online"/"registered" status icon) and calls to the number will start ringing directly in it.

3Outbound calls from a SIP client

Once the softphone is registered, it can dial out through this line on its own - you don't need to call any of our APIs for that, you dial directly from the client like from an ordinary phone line.

4Limits

• One registration per line - one set of credentials supports one registered device at a time. If you sign in with a second client, the first one will most likely lose its registration - don't rely on multiple devices on one line at once.
• Outbound from your own agent yes, full trunk peering no - the line's credentials let YOUR client register with US as a phone. Outbound calls from your own voice agent (ElevenLabs or another platform) DO work today though - through the relay, see Bring your own agent. You still can't connect your PBX as a peer carrier with its own routing for INBOUND calls from outside though - use forward routing to your PBX's number for that.
• Voice only - no video or other SIP extensions.