Guides

Bring your own agent

Want to connect your own voice platform - ElevenLabs Conversational AI on your own workspace, Vapi, Retell, or even a plain Asterisk/FreeSWITCH IVR - to a volai number instead of the built-in agent? This page covers both directions: inbound and outbound calls. For outbound, you also skip the agent surcharge of 2.50 CZK/min (~EUR 0.10) - you run (and pay for) the agent yourself on your own platform.

1Own agent vs. the built-in one

Both paths run on the same number and the same credit - they only differ in WHO runs the conversation logic and how much that costs on top:

2Inbound calls to your own agent

No new mechanics - just the existing mode: "sip" routing (same as for your own softphone, see SIP) with your platform's sipUri address. For an ElevenLabs SIP-trunk number registered on YOUR OWN workspace, that's one with the same number as your volai line:

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:+420601234567@sip.rtc.elevenlabs.io"}}'

And on your ElevenLabs account (Settings → Phone Numbers → Import → SIP trunk) you register this number with inbound_trunk_config:

{
  "provider": "sip_trunk",
  "phone_number": "+420601234567",
  "label": "My own agent",
  "inbound_trunk_config": {
    "allowed_addresses": ["81.31.45.0/24"],
    "media_encryption": "allowed"
  }
}

allowed_addresses above is our signalling range (81.31.45.0/24) - safer than the universal 0.0.0.0/0, which lets an INVITE in from anywhere. Both let the call through, but for an import without credentials the allowlist is the ONLY check - so use the range, not 0.0.0.0/0.

Using a different platform than ElevenLabs? Same principle - find out the SIP address it expects calls for your number on, and put that into sipUri. For Vapi, the same range goes into the BYO trunk's gateways.

For Vapi, the routing address is sip:<E164>@<credentialId>.sip.vapi.ai - find <credentialId> on your BYO SIP trunk in Vapi; the bare sip.vapi.ai belongs to native Vapi numbers and doesn't work for a number from us.

3Outbound calls from your own agent (relay)

This is the reverse direction - your platform dials out on its own. Most voice AI platforms (ElevenLabs included) can't permanently register a phone line as a SIP client - they only send a single authenticated call using your line's credentials. The phone network won't let such a call straight through to the destination number, so you route it through a short-lived relay connection instead:

1. Point your platform at your line

Fetch your line's SIP credentials:

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

The response returns server (for a softphone's REGISTER, see SIP) and outboundTrunkAddress SEPARATELY - they are not interchangeable.

And set outboundTrunkAddress - NOT server - as your platform's outbound trunk. For ElevenLabs, that's the outbound_trunk_config of the phone number in question (Settings → Phone Numbers → your number → Outbound calling), in exactly this shape:

{
  "outbound_trunk_config": {
    "address": "sip.volai.cz",
    "transport": "tcp",
    "media_encryption": "allowed",
    "credentials": {
      "username": "123456",
      "password": "a1b2c3d4e5f6"
    }
  }
}

2. Create a relay connection

Right before the call (the connection has a short lifetime, see the limits below), call:

curl -X POST https://volai.cz/v1/relay \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "from": "+420601234567"}'

{
  "id": "rl_4f2a91cd",
  "sipName": "volai_relay_2",
  "sipUri": "sip:volai_relay_2@sip.volai.cz",
  "expiresAt": 1756111760000,
  "callId": "c_9d4e2b7f"
}

You give US the destination number in to - the platform never sees it, it only gets the bare sipName from the response.

3. Tell your platform to call the sipName

For ElevenLabs, this means calling /v1/convai/sip-trunk/outbound-call with to_number set directly to the sipName:

{
  "agent_id": "agent_...",
  "agent_phone_number_id": "phnum_...",
  "to_number": "volai_relay_2"
}

agent_id is found on your agent in ElevenLabs, agent_phone_number_id is the phone_number_id of the imported number - the import response returns it, or you can read it off the Phone numbers list.

Using your own SIP client or PBX instead of ElevenLabs? Dial the full sipUri directly, like an ordinary SIP call - that restriction only applies to platforms that want a bare name without the sip: prefix.

4. What happens next

The phone network accepts the call under the name volai_relay_2, transfers it to your to and sets the visible caller ID to your from - the callee sees your volai line on their display, not the relay slot's internal name (only if the number has its own relay names - see Billing below, otherwise the callee sees volai's demo number). Once the call ends, the lease is released and the minutes are billed exactly like a regular outbound call - 0.92 CZK/min (~EUR 0.04), no agent surcharge.

The response confirming the call comes back only after the whole ring cycle (easily tens of seconds) - that's not an error, though a short timeout on your side could look like one while the call is still ringing.

4Troubleshooting

The most common messages with your own agent, and what to do about them:

5Billing

An outbound call through the relay is billed at the same rate as a regular outbound call - 0.92 CZK/min (~EUR 0.04) - with no agent surcharge whatsoever. Rates exclude VAT, like the whole price list.

Concurrency is limited (see the limits below): at most 1 active call per one of your numbers, and at most 2 per account at once.

The callee only sees your volai line if the number has its own relay names (relayNames) - without them, the lease falls back to the shared pool and the callee sees volai's demo number. If you're missing relay names, contact support.

6Limits, quotas and security

The cap is 1 active lease per number and at most 2 per account - a deliberate safeguard against one customer occupying the entire shared relay slot pool:

• from must be your own volai number - otherwise from_number_not_owned. Without this check, you could spoof someone else's line as your caller ID.
• Same gates as a regular call - do-not-call list (calls only, not SMS), automatic 30-day block after 3 failed attempts to the same number within 24 hours, premium-rate lines, protection against loops between volai numbers, the callee-number lock, and the general call rate limit. None of this can be bypassed through the relay.
• Pool full -> 503 capacity_busy - relay slots are a shared concurrency cap for the WHOLE platform, not just your account. On capacity_busy nothing is billed, try again shortly.
• The full REST reference (error codes, GET/DELETE on leases) is in the REST API reference.

Every API error carries cause (who fixes it) and action (what to do) - see Error format in the REST API reference.