Skip to main content
June 9, 2026 · By Piyush Sahoo · Updated November 3, 2026 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.
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. 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. Diagram of the three voice API planes between your application and Vobiz: REST commands, webhook events with VobizXML responses, and live audio over a WebSocket or RTP, with Vobiz connected to the phone network. Diagram of the three voice API planes between your application and Vobiz: REST commands, webhook events with VobizXML responses, and live audio over a WebSocket or RTP, with Vobiz connected to the phone network. 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. Sequence diagram of an outbound Vobiz call: the application sends Make Call, Vobiz returns request_uuid and sets up the call, sends a Ring event, sends StartApp to answer_url, runs returned VobizXML, posts digits to the action URL, and sends a final Hangup event. Sequence diagram of an outbound Vobiz call: the application sends Make Call, Vobiz returns request_uuid and sets up the call, sends a Ring event, sends StartApp to answer_url, runs returned VobizXML, posts digits to the action URL, and sends a final Hangup event.
  1. 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.
  2. Ring. If you set ring_url, Vobiz notifies it when the destination starts ringing.
  3. Answer. Vobiz sends Event=StartApp to your answer_url. This is the first moment your application controls the conversation.
  4. Instruct. Your server returns VobizXML. Vobiz runs each element in order, such as <Speak> followed by <Gather>.
  5. 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.
  6. End. When the call finishes, Vobiz sends Event=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. 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. 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.

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. 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. 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. 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.

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. 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 fires only when your application stops the stream, 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. Diagram of capacity limits: in an illustrative example, calls leave your queue through a CPS gate of 2 calls per second, then fill a concurrency pool with 120 of 160 channels busy. Placing a call past either limit returns a 429. The example formula is 2 times 60 seconds equals 120 channels. Diagram of capacity limits: in an illustrative example, calls leave your queue through a CPS gate of 2 calls per second, then fill a concurrency pool with 120 of 160 channels busy. Placing a call past either limit returns a 429. The example formula is 2 times 60 seconds equals 120 channels. 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.
  1. Rate. 7,200 calls ÷ 3,600 seconds = 2 calls per second, so you need at least 2 CPS.
  2. 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.
  3. 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.
  4. 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 does India add to a voice API design?

If you call within India, regulation shapes the call flow as well as the paperwork. Build these constraints in from the start, and use the Vobiz India calling regulations as your working reference.
  • KYC. You need to complete KYC before you rent Indian numbers. The eligibility rules cover who can use domestic routes.
  • Media anchoring. Both call legs must stay within India. A call that breaks this rule ends with the violates_media_anchoring hangup cause.
  • Number series. TRAI’s July 2026 statement says it has mandated 140xx numbers for promotional calls by entities of any sector. It has also mandated 1600xx numbers for service and transaction calls by regulated BFSI entities to their existing customers, and by government entities for government-to-citizen communication.
  • Consent. Commercial calls need explicit digital consent. See the UCC guidance.
Regulations change, so confirm your use case against the current rules before launch.

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.

How Vobiz handles it

Vobiz gives you the planes described above in one account, available in 130+ countries. Your first quickstart call is a real, billed call. Use your own credentials, and confirm the destination number before you place it.

FAQ

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.
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.
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.
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.
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.
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

Sources

Get started with Vobiz

Set up your first programmable call in minutes.