Voice
Place and receive calls,from your own code.
One request starts an outbound call. Inbound calls hit your answer URL and your app decides what happens next. It runs on the same place and receive engine that powers TelVox Dial, in developer preview.
Outbound
Start a call with calls.create.
Give us a from, a to and an answer URL. TelVox queues the call, dials it, and walks it through its lifecycle, streaming each transition to your status callback so your application stays in sync.
curl https://api.telvox.dev/v1/calls \
-H "Authorization: Bearer $TELVOX_API_KEY" \
-d from="+14155550100" \
-d to="+14155550199" \
-d answer_url="https://your.app/voice/answer" \
-d status_callback="https://your.app/voice/status"{
"sid": "CA9f0c…",
"from": "+14155550100",
"to": "+14155550199",
"direction": "outbound-api",
"status": "queued",
"answer_url": "https://your.app/voice/answer",
"status_callback": "https://your.app/voice/status",
"date_created": "2026-06-21T18:04:11Z"
}POST https://your.app/voice/status
Content-Type: application/json
{
"call_sid": "CA9f0c…",
"status": "answered", // initiated → ringing → answered → completed
"from": "+14155550100",
"to": "+14155550199",
"answered_by": "human", // AMD result, when enabled
"timestamp": "2026-06-21T18:04:19Z"
}
# respond 200 OK to acknowledgeCall states
streamed to your status callback
- queued
- initiated
- ringing
- in-progress
- completed
- busy
- no-answer
- failed
- canceled
Inbound
Answer calls with a webhook.
Point a number's answer URL at your endpoint. When a call arrives, TelVox POSTs the context to you and your app replies with a call-control document. There is no call state to hold on your side.
POST https://your.app/voice/answer
Content-Type: application/json
{
"call_sid": "CAa31d…",
"direction": "inbound",
"from": "+14155550123",
"to": "+18005550100", // your assigned number
"answered_by": null
}// your 200 response: a call-control document
{
"instructions": [
{ "play": { "text": "Thanks for calling TelVox." } },
{ "gather": {
"num_digits": 1,
"action_url": "https://your.app/voice/menu"
} }
]
}The call-control document is the primary model: a JSON instruction set (play / gather / dial / record / hangup). A declarative markup dialect is on the roadmap. See call control & IVR
Real engine capabilities
Built for answer rate and reach.
These aren't preview features. They're shipped capabilities of the engine Dial runs on, now reachable from your code.
Answering Machine Detection
Connect can tell a live human from a machine and surface the result on the status callback (answered_by), so your code can branch: drop a voicemail, retry later, or hand the call straight to an agent.
Alternate-number failover
When the primary number doesn't connect, the engine can automatically try phone2 and phone3 on the same contact before giving up. It's the same failover ladder Dial dials on.
Caller-ID & DID rotation
Present a local number to lift answer rates. Rotate caller ID round-robin, keep it sticky per contact, or match the destination's area code, all driven from your DID pool.
Every field, enum and payload above is illustrative. Connect's API is v0.x and exact shapes may differ at v1. The Call resource reference tracks the current shape.
Call resource referenceQuestions
Voice API FAQ
The capability is real. TelVox's engine already places and receives calls in production for Dial, with AMD, alternate-number failover and caller-ID rotation shipped. What is versioned v0.x is the public REST surface: the exact endpoints, field names and enums shown here are illustrative and may change before general availability.
Next step
Put a call in your product.
Sign up and we'll walk the Voice API, the call lifecycle and how it maps to your stack.