TelVox · Connect · Quickstart

Make your first call

This quickstart places a real outbound call and walks the request from start to finish: get preview credentials, point a call at an answer_url, POST to /v1/calls, and handle the status callback as the call rings, answers and completes. Snippets are shown in cURL, Node and Python.

Before you start

You'll need:

• Preview credentials — request access from the developer preview and we'll provision a sandbox SID, an API key and a test number.
• A publicly reachable URL for your answer_url and status_callback (a tunnel like a local-dev forwarding service works while testing).
• Your API key exported as an environment variable — TELVOX_API_KEY.

1 · Get your API key (preview)

Requests authenticate with an API key — a SID plus a secret — sent as a bearer token. During the preview, key issuance is provisioned with our team rather than self-serve; you'll receive a sandbox key to use below. Keep the secret server-side and never ship it to a browser. See Authentication & API keys for the full model, including short-lived access tokens for WebRTC clients.

export TELVOX_API_KEY="sk_preview_…"   # provisioned with the team during preview

2 · Set up an answer_url

When a call connects, TelVox makes a request to your answer_url and your app responds with a call-control document — a small JSON list of instructions like play, gather, dial, record and hangup. Host this at a public URL before you place the call. (An XML markup dialect is on the roadmap — JSON is the primary model today.)

// illustrative — shape may differ at GA
// your server responds to TelVox's answer_url request with a
// JSON call-control document. play, then gather digits.
{
  "instructions": [
    { "verb": "play", "text": "Thanks for calling. Please hold." },
    {
      "verb": "gather",
      "num_digits": 1,
      "action_url": "https://your.app/voice/menu",
      "prompt": "Press 1 for sales, 2 for support."
    }
  ]
}

See Call-control markup for the full instruction set.

3 · Place the call

With your key exported and your answer URL live, POST to /v1/calls with from, to and your answer_url. Pick a language tab:

# illustrative — shape may differ at GA
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"

TelVox responds with the created Call resource. The sid identifies the call across the API and in every callback:

{
  "sid": "CA8f3c2a9b1d4e5f60",
  "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-22T17:04:11Z"
}

4 · Handle the status callback

As the call advances, TelVox POSTs to your status_callback across the lifecycle — initiated, ringing, answered and completed. Acknowledge each delivery with a 2xx; deliveries arrive over signed, SSRF-safe egress and retry with backoff if your endpoint is slow or errors.

// illustrative — shape may differ at GA
// TelVox POSTs to your status_callback as the call advances:
// initiated → ringing → answered → completed
POST https://your.app/voice/status
Content-Type: application/json

{
  "call_sid": "CA8f3c2a9b1d4e5f60",
  "status": "answered",
  "event": "answered",
  "from": "+14155550100",
  "to": "+14155550199",
  "timestamp": "2026-06-22T17:04:19Z"
}

// respond 200 to acknowledge. respond 2xx within the
// timeout or TelVox retries with backoff.

See Webhooks & callbacks for the full event list and signature verification.

What's next

• Record the call — capture audio with AES-256-GCM at rest and retrieve it via a short-lived signed URL.
• Build an IVR — chain play, gather and route instructions into a menu.
• Subscribe to events — react to call lifecycle events across your application.
• Call resource reference — every property, status enum and endpoint on the Call resource.