Ultravox

Ultravox agents can place calls through your Vonyx trunk and answer calls to your Vonyx numbers. Both directions use plain SIP: Ultravox dials 43.204.9.41 for outbound calls, and Vonyx forwards inbound calls to your Ultravox SIP domain.

Before you start

A Vonyx SIP trunk with a number attached
The trunk's username and password, from the console
An Ultravox account with SIP enabled. Ultravox charges extra for SIP minutes, and SIP must be enabled for your account.
An Ultravox API key (sent in the X-API-Key header)
An Ultravox agent. Copy its agent ID.

Outbound calls

Build the SIP addresses

Ultravox takes SIP URIs, not bare phone numbers. Point to at the Vonyx server and set from to your Vonyx number.

Field	Value
`to`	`sip:[email protected]:5060` (the number you're calling)
`from`	`sip:[email protected]` (your Vonyx number)
`username`	`your_trunk_username`
`password`	`your_trunk_password`

UDP is the default. To use TCP, add ;transport=tcp to to, for example sip:[email protected]:5060;transport=tcp. Don't use ;transport=tls, because Vonyx doesn't support TLS.

Create an agent call

Call the Create Agent Call endpoint with a medium.sip.outgoing block. Ultravox sends the INVITE as soon as the call is created, so the response has no joinUrl.

outbound.sh

curl -X POST https://api.ultravox.ai/api/agents/YOUR_AGENT_ID/calls \
  -H "X-API-Key: $ULTRAVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "medium": {
      "sip": {
        "outgoing": {
          "to": "sip:[email protected]:5060",
          "from": "sip:[email protected]",
          "username": "your_trunk_username",
          "password": "your_trunk_password"
        }
      }
    }
  }'

The phone rings, and the agent talks once the call is answered.

Inbound calls

Ultravox accepts an incoming INVITE only when it comes from an allowed IP address and its To address matches one of your agents. You set both in your account's SIP configuration.

Find your Ultravox SIP domain

curl https://api.ultravox.ai/api/sip \
  -H "X-API-Key: $ULTRAVOX_API_KEY"

The response's domain field is your account's SIP domain. It also returns your current allowedCidrRanges and allowedAgents.

Allow Vonyx and route the number to your agent

Add Vonyx's server as an allowed range, and add an agent allowance whose toUserPattern matches your Vonyx number. The pattern is a regular expression matched against the user part of the INVITE's To address. Without a pattern, Ultravox only matches agent_YOUR_AGENT_ID, and Vonyx can't send that user part.

curl -X PATCH https://api.ultravox.ai/api/sip \
  -H "X-API-Key: $ULTRAVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowedCidrRanges": ["43.204.9.41/32"],
    "allowedAgents": [
      { "agentId": "YOUR_AGENT_ID", "toUserPattern": "^91XXXXXXXXXX$" }
    ]
  }'

Include any ranges and allowances you already have, from the previous step. You can add up to 20 allowances. Ultravox checks them in order. For a single agent that answers every number, use the pattern .*.

Point Vonyx at Ultravox

In the Vonyx console, open the trunk, turn on Inbound calls and set Inbound address to your SIP domain from the first step, with no sip: and no user part. See inbound calls.

YOUR_ULTRAVOX_SIP_DOMAIN

Routing more than one number

Add one allowance per number, each with its own agentId and toUserPattern. To decide in code, set a fallbackHandler webhook on the SIP configuration. Ultravox calls it for INVITEs that match no allowance, and the webhook replies with startAgentCall, startCall or reject.

Test the connection

Run the outbound request with your own mobile as to. Your phone should ring with your Vonyx number as caller ID.
Call your Vonyx number from another phone. The agent should answer.
If a call fails, wait for it to end, then get its SIP logs from Ultravox. Use GET https://api.ultravox.ai/api/calls/YOUR_CALL_ID/sip_logs with your X-API-Key header; it redirects to the log file. Then see troubleshooting.

Limitations

DTMF and call transfer are not available on Vonyx yet. Don't give Ultravox agents the playDtmfSounds tool or transfer tools on Vonyx calls.
New accounts make 1 call at a time (raise limits).
Audio uses G.711 (PCMU or PCMA) at 8 kHz. Ultravox's HD codecs (G.722, Opus) aren't used on Vonyx calls.
No TLS or SRTP. Use UDP or TCP.
Ultravox bills SIP minutes on top of call minutes.

Troubleshooting

Problem	Fix
Outbound call fails right away	Check `username` and `password` match the trunk, and that `to` is a full SIP URI (`sip:[email protected]:5060`), not a bare number.
Call connects with wrong or blocked caller ID	`from` must use one of your Vonyx numbers.
Second call fails while one is live	You're at your channel limit. Raise limits.
Inbound call is rejected	Check `allowedCidrRanges` contains `43.204.9.41/32` and a `toUserPattern` matches your number. Ultravox rejects calls that match no agent and have no fallback handler.
Inbound call never reaches Ultravox	Check the trunk's inbound address is exactly your Ultravox `domain`, and that Inbound calls is on.
One-way or no audio	Allow RTP over UDP on ports 10000–20000 from `43.204.9.41`.
Call fails during setup with a codec error	Vonyx only offers PCMU and PCMA. Both are on Ultravox's supported list, so check any device in between isn't rewriting the SDP.

On this page