A voice API turns a phone call into something your code can drive: HTTP requests to start or change it, webhooks when it changes state, and optionally a live audio stream. This post is about what happens once the call is live, including the three channels your app uses, how to design webhook handlers, and how to size capacity.
A voice API is a set of web interfaces that lets your software place, answer, and control phone calls. Your code sends HTTP requests to start or change a call, receives webhooks (callbacks) when the call changes state, and can stream live audio, while the provider runs the telephone network connections.
This guide explains how that works once a call is live: the three channels your application uses, each step of a call, how to design webhook handlers, when audio reaches your servers, and how to size capacity. Vobiz details link to their reference pages, so you can move from concept to implementation.
Note: Key takeaways
- A voice API separates a phone call into three planes: commands you send, events you receive, and media, the audio itself.
- Your application answers an event with VobizXML, or changes a live call with a REST request. Most production systems use both.
- Webhook handlers must be fast, idempotent, and signature-checked. A slow answer handler is heard by the caller as silence.
- Capacity has separate limits: CPS and concurrency govern calls, and a request quota governs other API traffic.
- Size channels with calls per second × average seconds per call, and count ringing time.
What is a voice API?
With a voice API, a phone call becomes a resource your software can create, inspect, and change. The call still travels over the public switched telephone network (PSTN) or a SIP connection. Your application, though, deals with HTTP requests, identifiers, and events instead of switches and carrier contracts.
The term is used loosely. Some vendors, such as Typecast, use it to include speech recognition and speech synthesis. This article means the telephony kind, and this table separates it from its neighbours.
| Technology | What it gives you | What you still own | Reach for it when |
|---|---|---|---|
| Voice API | Programmatic calls, events, call control, and optional audio streams | Call logic and webhook servers | Your software decides what happens on each call |
| SIP trunk | A connection between the phone network and your SIP system | The PBX or SIP platform that handles the call | You already run SIP infrastructure |
| Speech API | Speech-to-text or text-to-speech | Getting audio to and from the phone call | You need the speech models, not the phone connection |
| Voice agent platform | A managed speech and conversation pipeline | Agent design, plus a phone connection | You want a managed AI layer instead of building your own |
These layers combine. An AI voice agent can use a speech API for transcription, a language model for decisions, and a voice API or trunk for the phone call.
How does a voice API work? The three planes
The clearest way to understand a voice API is to separate its traffic by job. A call has three planes, and each has its own transport, timing, and failure modes.
| Plane | Who starts it | Transport | Timing pressure | What a fault sounds like |
|---|---|---|---|---|
| Command | Your application | REST over HTTPS | Low. You choose when to send | The call doesn't start or doesn't change |
| Event | Vobiz | Webhook over HTTPS, with VobizXML in some responses | High on instruction requests | Silence while Vobiz waits for instructions |
| Media | The call or your stream setup | WebSocket or RTP | Continuous | Choppy, delayed, or one-way audio |
This separation shapes your architecture. A web service can handle the command and event planes. The media plane behaves more like a real-time service, because each active stream holds a connection open for as long as it runs.
A simple IVR may never touch the media plane, because Vobiz plays prompts and collects input for you. A custom AI agent lives there.
What happens during a voice API call?
Here is an outbound call from first request to hangup. It uses a one-question menu, and the shape stays the same for longer flows.
- Create. You send a Make Call request with from, to, and answer_url. The response carries a request_uuid, which identifies the call. A successful response means Vobiz accepted the request, not that anyone answered.
- Ring. If you set ring_url, Vobiz notifies it when the destination starts ringing.
- Answer. Vobiz sends Event set to StartApp to your answer_url. This is the first moment your application controls the conversation.
- Instruct. Your server returns VobizXML. Vobiz runs each element in order, such as Speak followed by Gather.
- Loop. When an element with an action URL completes, Vobiz sends its result there and asks for more instructions. A menu choice arrives as Digits, for example.
- End. When the call finishes, Vobiz sends Event set to Hangup to your hangup_url. Use this event as your authoritative end-of-call signal.
An inbound call skips steps 1 and 2. Vobiz finds the application attached to the dialed number and requests its answer URL.
Call legs and identifiers
When Dial connects a second party, the original call is the A-leg and each dialed call is a B-leg. Each leg has its own identifier, and a call record points back to the A-leg through parent_call_uuid. You can transfer each leg independently. The Dial transfer visualizer steps through a common case, an AI agent handing a caller to a human, with every webhook and XML response along the way.
Store the identifier the moment you create a call, then write every later event against it. VobizXML is stateless, so your application keeps the conversation state.
Why a call ended
The call record carries hangup_source, which says who ended the call, and hangup_cause_code, which says why. Treat them separately. A hangup by the caller and a hangup by your own VobizXML both end the call, but they mean different things in your reports. The hangup cause reference lists each code and its next step.
How should you design webhook handlers?
Voice webhooks come in two kinds, and they have different contracts. Mixing them up is a common source of production bugs.
| Instruction request | Notification | |
|---|---|---|
| Examples | answer_url, action URLs | ring_url, hangup_url, recording and stream events |
| What Vobiz needs | VobizXML in the response | An HTTP 200 acknowledgement |
| Time budget | Aim for 1 to 2 seconds | Respond within 3 seconds |
| If you're slow | The caller hears silence | Vobiz may treat delivery as failed and retry |
| Good pattern | Serve decisions from cached data | Queue the event, acknowledge, and process later |
Four rules follow from that contract:
- Make handlers idempotent. Vobiz retries failed callbacks up to 3 times with exponential backoff, so duplicates can happen. A unique key on the call identifier and event type works for one-time events such as Hangup. Events that repeat on a call, such as ClearedAudio, need a different guard.
- Plan for answer URL failure. Set fallback_url on Make Call, or fallback_answer_url on an application, so a backup can take over. A static backup that apologises and offers a callback is enough for many teams.
- Verify the sender. Callback URLs must use HTTPS. The X-Vobiz-Signature-V2 and X-Vobiz-Signature-V3 headers carry HMAC-SHA256 signatures of the URL and a nonce, not the body. They appear when the callback URL has auth credentials configured, and coverage varies by callback type. Configure those credentials, then reject requests that lack a signature you expect.
- Expect more stream events than you think. The stream docs report a 125-second conversational call producing 15 status callbacks, because ClearedAudio fires on every barge-in. The Stream events visualizer walks through that lifecycle event by event, from start and media to checkpoint, barge-in, and stop.
What is call control?
Call control means changing what a call does. You have two tools, and they answer different triggers.
VobizXML is declarative. Vobiz asks what to do next, and you return a list of instructions. Use it when the call itself caused the next step, such as a digit press or a finished recording. To prototype a flow before you write a handler, the Vobiz XML Builder lets you pick and order elements and copy the XML it generates.
REST is imperative. You act on a live call at any time. Use it when something outside the call triggers the change, such as a supervisor action, a timer, or a fraud rule.
| You want to | In VobizXML | Over REST on a live call |
|---|---|---|
| Speak text | Speak | Speak text |
| Play audio | Play | Play audio |
| Collect digits or speech | Gather | Transfer to a URL that returns Gather |
| Reach another party | Dial | Transfer a call to new VobizXML |
| Send tones | DTMF | Send DTMF |
| Record | Record | Record Calls API |
| Stream audio | Stream | Start an audio stream |
| Join a conference | Conference | Transfer to a URL that returns Conference |
| End the call | Hangup | Hang up a call |
Answering machine detection sits in neither column. You enable it with parameters on Make Call, and it applies to outbound calls.
The same pattern across providers
The event-and-instruction model is common across the industry, and the instruction format is what mostly changes. Vobiz uses VobizXML, an XML response to a webhook. Other voice APIs may use a markup language, a JSON structure, or commands sent in response to webhook events.
If you know one of these models, you already understand the flow of the others. The vocabulary and event names are the parts to relearn.
How does call audio reach your application?
You have three options, and the main question is who owns the conversation pipeline.
| Path | How audio moves | You own | Fits |
|---|---|---|---|
| Vobiz handles media | Vobiz plays prompts and collects input from your VobizXML | Call logic only | IVRs, alerts, reminders |
| WebSocket stream | Vobiz forks call audio to your WebSocket, and you can send audio back | Speech-to-text, agent logic, text-to-speech, voice activity detection, barge-in, and state | Custom AI pipelines, live transcription |
| SIP trunk | RTP between the network and your SIP platform | A SIP system or managed platform | PBXs and platforms such as LiveKit, Vapi, or Retell |
The SIP vs WebSockets guide compares the last two in detail. One transport difference matters here: RTP normally runs over UDP, so a lost packet is skipped, while a WebSocket runs over TCP, so a lost packet is resent and can add jitter on a poor network. Here are the two AI paths side by side:
They aren't exclusive. A call can arrive on a SIP trunk and still be piped to your WebSocket server with a Stream element, so SIP handles routing and the socket handles audio.
Sizing a WebSocket stream
Stream audio is Base64-encoded, and Base64 turns every 3 bytes into 4 characters. That adds a third to the raw bitrate. The table below is our own calculation from the Vobiz stream formats and shows one direction only. It excludes JSON framing and TCP and TLS overhead.
| Format | Available for | Raw bitrate | With Base64 | Per 100 calls |
|---|---|---|---|---|
| μ-law, 8 kHz | Inbound and outbound | 64 kbit/s | 85 kbit/s | 8.5 Mbit/s |
| L16, 8 kHz | Inbound and outbound | 128 kbit/s | 171 kbit/s | 17.1 Mbit/s |
| L16, 16 kHz | Inbound and outbound | 256 kbit/s | 341 kbit/s | 34.1 Mbit/s |
| L16, 24 kHz | Outbound only | 384 kbit/s | 512 kbit/s | 51.2 Mbit/s |
The μ-law figure matches the 64 kbit/s rate of G.711, the ITU-T telephone codec. Sizes matter less than matching formats, though. Inbound and outbound audio are configured separately, so read the inbound format from start.mediaFormat on each connection.
Keeping a conversation responsive
People notice delay quickly. ITU-T G.114, a 2003 Recommendation that ITU lists as in force, recommends against exceeding 400 ms of one-way delay for general network planning, and notes that most applications aren't significantly affected below 150 ms. An AI agent's thinking time comes on top of network delay, so measure each stage of your pipeline.
Interruptions need their own design. When your voice activity detector confirms that a caller is speaking over the agent, send clearAudio to drop queued playback. The docs recommend 20 to 60 ms playback chunks for responsive barge-in, because a large buffer keeps talking after the caller interrupts.
Watch stream health as well. DegradedStream warns you while the stream is still up, which gives you time to adapt. StopStream reports that the stream session ended, whatever the cause, so rely on Hangup to detect the end of a call.
How do you scale a voice API?
Three limits apply, and each one fails differently. Treat them as separate budgets.
| Limit | What it controls | Scope | How to stay inside it |
|---|---|---|---|
| CPS | How fast you start calls | Your account's provisioned capacity | Pace calls from a queue |
| Concurrency | Calls active at the same moment, including those still ringing | Your account's provisioned capacity | Size channels from your call duration |
| Request quota | Other Voice API requests, such as listing calls | The parent account, shared with sub-accounts | Pace requests and prefer webhooks to polling |
Inbound calls use the same concurrency pool. A call over the limit is rejected with a 429 or SIP 503.
Make Call has one more safeguard. If too many Make Call requests fail, an error budget briefly blocks further requests of that type. So fix a 4xx error before you retry it, and back off with jitter on a 429.
A worked sizing example
Suppose you need to place 7,200 reminder calls in one hour. Assume each call rings for 15 seconds and talks for 45 seconds.
- Rate. 7,200 calls ÷ 3,600 seconds = 2 calls per second, so you need at least 2 CPS.
- Channels. Little's law says the average number of items in a system equals their arrival rate multiplied by the time each one spends there. So 2 × 60 seconds = 120 channels on average, before any headroom.
- Webhooks. An answered call with one menu produces a ring event, an answer request, an action request, and a hangup event. At 2 calls per second, plan for about 8 requests per second, plus any extra events you enable.
- Streams. If the same calls used μ-law streams, 120 calls would need about 10 Mbit/s in each direction, before framing overhead.
The numbers change quickly with duration. At a 3-minute average, the same 2 calls per second need 360 channels. Add headroom for peaks, then test it with the CPS and concurrency visualizer.
What to check when a production call misbehaves
| What you notice | Where to look first | Next step |
|---|---|---|
| Silence after answer | answer_url response time | Cache lookups and set a fallback URL |
| Duplicate records | Retried callbacks | Add an idempotency key |
| 429 while placing calls | CPS or concurrency use | Check which limit you hit and add pacing |
| Garbled stream audio | The stream's declared format | Decode with start.mediaFormat, and declare each playAudio format |
| Calls end unexpectedly | hangup_source and hangup_cause_code | Follow the hangup cause reference |
What does a voice API cost?
Most voice API bills have the same parts: per-minute usage, number rental, and any add-on services. For an AI agent, speech and language model costs sit on top.
On Vobiz, a call's per-minute rate depends on the destination number. See the Vobiz pricing page and your Vobiz Console for current rates.
After each call, the call record shows what you were billed through billed_duration, total_rate, and total_amount. If you need more capacity, you can preview the monthly CPS or concurrency price before you buy.
How to evaluate a voice API
Feature lists tend to look alike. These questions reveal more about how a provider behaves in production.
| Ask | Why it matters |
|---|---|
| What is the retry policy for webhooks? | It sets how you design idempotency |
| How are webhooks signed, and what does the signature cover? | It decides how you authenticate events |
| Which audio formats are available in each direction? | It determines your codec and speech pipeline |
| How are limits scoped and reported? | It tells you how your dialer has to pace itself |
| What explains a failed call? | Detailed hangup data shortens debugging |
| What rules apply in your calling region? | Local rules can change your routing and numbers |
How Vobiz handles it
Vobiz gives you the planes described above in one account,.
- Commands. The Vobiz API authenticates with Auth ID and Auth Token, sent as the X-Auth-ID and X-Auth-Token headers. SDKs are available for Python, Node.js, Java, Go (Golang), Ruby, PHP, and C#.
- Events and control. Webhooks (callbacks) report call, recording, conference, and stream events. VobizXML controls the call, and the XML builder helps you draft it.
- Media. Audio streams reach your WebSocket application, and SIP trunks connect your SIP systems. Registered SIP clients use endpoints.
- Records. Call detail records keep each call's timing, cost, and hangup data for reporting.
Your first quickstart call is a real, billed call. Use your own credentials, and confirm the destination number before you place it. Before you call a new destination, check the calling regulations, KYC and UCC consent requirements that apply to it.
FAQ
Is programmable voice the same as a voice API?
In everyday use, yes. Programmable voice describes the capability of controlling calls with software, and a voice API is the interface you use to do it. Providers may use either term for the same product, so compare what each one actually offers.
What is the difference between a voice API and a SIP trunk?
A voice API lets your application control calls through HTTP requests and webhooks. A SIP trunk connects the phone network to a SIP system, such as a PBX, which then handles the call. You can use both, depending on where your call logic runs.
How do you make a voice API call?
Send an authenticated Make Call request with a from number, a to number, and an answer_url. When the call is answered, Vobiz requests VobizXML from that URL and runs it. Real calls are billed, so use your own credentials and confirm the destination first.
How do you authenticate with a voice API?
Vobiz authenticates REST requests with the X-Auth-ID and X-Auth-Token headers, which carry your Auth ID and Auth Token. Keep both on your server. Webhooks travel the other way, so validate their HMAC signatures to confirm that Vobiz sent them.
How much does a voice API cost?
Most voice APIs bill per minute, plus number rental and add-ons. On Vobiz, the per-minute rate depends on the destination number. Check the Vobiz pricing page and your Vobiz Console for current rates. AI agents add speech and language model costs.
Can a voice API record and transcribe calls?
Yes, with Vobiz. You can record with the VobizXML Record element or the Record Calls API. Transcription is an option on the Record Calls API, so use that route when you need speech-to-text output from a recording.
Further reading on Vobiz
- How VobizXML works · Vobiz webhooks (callbacks) · Validating callbacks
- Voice streaming over WebSockets · SIP vs WebSockets · Vobiz API rate limits
- AI voice agents · Cloud IVR · Automated outbound calling
- What is an IVR? · What is SIP trunking? · What is a DID number?
Sources
- IETF, "RFC 3261: SIP: Session Initiation Protocol".
- IETF, "RFC 3550: RTP: A Transport Protocol for Real-Time Applications".
- IETF, "RFC 6455: The WebSocket Protocol".
- IETF, "RFC 4648: The Base16, Base32, and Base64 Data Encodings".
- ITU-T, "G.711: Pulse code modulation (PCM) of voice frequencies".
- ITU-T, "G.114 (05/2003): One-way transmission time", and its status page.
- TRAI, "Press Release No. 91/2026: clarifications regarding functioning of designated 1600 series and 140 series" (July 10, 2026).
- Wikipedia, "Public switched telephone network", "G.711", and "Little's law".
- Typecast, "What Is a Voice API and How Can You Use It?" (February 19, 2026).
Get started with Vobiz — Set up your first programmable call.
For voice AI agents that need a programmable phone line, Vobiz offers a voice API and SIP trunking built for them.
Top comments (0)