TelVox · Connect
Place and receive calls, from your own code.
A single request starts an outbound call; inbound calls hit your answer URL and your app decides what happens next. It runs on the same place/receive engine that powers TelVox Dial.
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"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.
{
"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
- 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's 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 — 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 — driven from your DID pool.
Every field, enum and payload above is illustrative — Connect is a developer preview and exact shapes may differ at GA. 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's in developer preview is the public REST surface: the exact endpoints, field names and enums shown here are illustrative and may change before general availability.
Pass a status_callback URL when you create the call. TelVox POSTs to it as the call moves through its lifecycle — initiated, ringing, answered and completed — over the same signed, SSRF-safe egress that powers Dial's webhooks. You acknowledge each event with a 200.
Assign a number to your application and point its answer URL at your endpoint. When a call comes in, TelVox POSTs the call context to that URL and your app replies with a call-control document — play audio, gather digits, dial, record or hang up. No call state to manage on your side.
When Answering Machine Detection is enabled, the status callback includes answered_by — typically human or machine. That lets your application decide in real time whether to connect an agent, play a message, or leave a voicemail. AMD is a real, shipped capability.
Yes — that's part of the Call resource. You can update an in-progress call to redirect it to a new call-control document or end it. The full method and parameter shapes live in the Call resource reference, which is illustrative during the preview.
Put a call in your product.
Join the developer preview and we'll walk the Voice API, the call lifecycle and how it maps to your stack.