Program an outbound voice call

POST /api/v1/voice/calls originates a call, and the programmable voice surface decides what that call does once the far end answers. You have two options, picked per call:

answer_url — an HTTPS endpoint on your server. When the call answers, Orbit POSTs the call metadata to it and expects a JSON list of verbs (say, play, gather, dial, hangup, …) that runs the call — the Twilio voiceUrl / Vonage answer_url model, applied to outbound.
staticVerbs — the verb list embedded in the create request itself (TwiML-Bin style), for flows that never change between calls.

Both run through the same verb engine documented in the Programmable Voice DSL reference; this guide walks the whole loop — provision a number, place the call, serve the verbs, track progress, then fetch the recording and the transcript.

Every outbound leg terminates through the Devotel softswitch. You cannot route outbound voice through Telnyx, DIDWW, or an arbitrary carrier — a carrier-selection field a returned verb carries is ignored.

1. Provision a voice-capable number

You need one owned DID for the caller ID. If you do not already have one, work through Buy and provision numbers — search inventory with capabilities=sms,voice, purchase, and wait until the order reports the line provisioned. Two distinct models sit on that number:

Inbound — a caller dials your DID and the number’s inbound route decides what happens. Set it to an answer_url route if you want the same verb-driven treatment inbound.
Outbound — nothing to configure on the number. You pass it as from on POST /api/v1/voice/calls, and the call enters the verb surface the moment the far end picks up.

2. Place the call

Send to, optionally from (falls back to a tenant default when omitted), and one of the two control modes. Also accepted here: record (capture the call audio), amd (carrier-side answering-machine detection — judge the result server-side before you deliver a message meant for a human), metadata (an arbitrary JSON object persisted on the call row and echoed back in every webhook), plus campaignId and orgTimezone for spend-cap and quiet-hours bookkeeping.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+16572262362",
    "answer_url": "https://app.example.com/voice/outbound-answer",
    "answer_method": "POST",
    "answer_fallback": "safe-default",
    "record": true,
    "amd": true,
    "metadata": { "order_id": "ord_8842" }
  }'

Node SDK — @devotel/orbit

import { Orbit } from "@devotel/orbit";

const orbit = new Orbit({ apiKey: "dv_test_sk_YOUR_KEY" });

const { data: call } = await orbit.voice.calls.create({
  to: "+14155552671",
  from: "+16572262362",
  record: true,
  amd: true,
  metadata: { order_id: "ord_8842" },
});
// call.id ("call_…") — the handle for status polling, hangup, recordings.

Python SDK — orbit-sdk

from orbit_sdk import OrbitClient

client = OrbitClient.from_api_key("dv_test_sk_YOUR_KEY")

call = client.voice.create(
    to="+14155552671",
    from_="+16572262362",
    record=True,
    amd=True,
    metadata={"order_id": "ord_8842"},
)
call_id = call["data"]["id"]

A 2xx returns the created call in the standard envelope; data.id is the call_… handle every later step uses. answer_url or staticVerbs? They are mutually exclusive — the API rejects a request carrying both, and a request carrying neither places a plain call with no programmable control. Reach for staticVerbs when the flow is fixed; reach for answer_url the moment the flow depends on the callee, your data, or input collected mid-call:

cURL — staticVerbs variant

curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "record": true,
    "staticVerbs": [
      { "verb": "say", "text": "Your appointment is confirmed for Friday." },
      { "verb": "hangup" }
    ]
  }'

answer_fallback governs what the call does when your answer_url cannot be served — safe-default (a short apology then hangup), voicemail, or decline. Between this and the production guardrails below, that is the whole reliability contract of the surface.

3. Implement the answer_url handler

The full handshake — the request body Orbit sends, the response shapes, and every verb — is in the Programmable Voice DSL reference. In short: Orbit POSTs { callSid, from, to, dialedE164, routeId, organizationId } to your URL, and your handler must reply with JSON — either { "verbs": [...] } or a bare verb array — within the fetch budget (5s default, 10s hard cap). On timeout, non-2xx, non-JSON, or an empty array, the answer_fallback you set on the route or the call runs instead, so a callee never lands on dead air.

Verify the signature before you serve verbs. Configure a signing secret on the route, and Orbit signs every request to your answer_url with HMAC-SHA256 in X-Devotel-Timestamp / X-Devotel-Signature. Verify against the raw request body — re-serializing parsed JSON breaks the comparison. Hash the raw bytes, reject timestamps older than a few minutes, and answer 401 on mismatch. This scheme is separate from customer-webhook signatures; the exact contract is in Verifying the request came from Orbit.

A complete minimal handler — greet, play a file, bridge to a PSTN destination, hang up:

Express

import crypto from "node:crypto";
import express from "express";

const app = express();
const ANSWER_SECRET = "your_route_signing_secret";

app.post("/voice/outbound-answer", express.raw({ type: "*/*" }), (req, res) => {
  const timestamp = req.headers["x-devotel-timestamp"];
  const signature = req.headers["x-devotel-signature"];
  const raw = req.body.toString("utf-8");

  const expected =
    "sha256=" +
    crypto.createHmac("sha256", ANSWER_SECRET).update(`${timestamp}.${raw}`, "utf-8").digest("hex");
  const ok =
    signature &&
    expected.length === String(signature).length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(String(signature)));
  if (!ok) return res.status(401).json({ error: "Invalid signature" });

  const call = JSON.parse(raw); // { callSid, from, to, dialedE164, … }

  res.json({
    verbs: [
      { verb: "say", text: "Hello — this is Acme confirming your appointment." },
      { verb: "play", url: "https://cdn.example.com/outbound/details.wav" },
      {
        verb: "dial",
        callerId: "+16572262362",
        timeout: 25,
        target: [{ type: "phone", number: "+14155550123" }],
      },
      { verb: "hangup", reason: "Call complete" },
    ],
  });
});

app.listen(3000);

Branch on collected DTMF. gather collects input mid-call and POSTs the result to its actionHook, which returns the next verb list — the IVR-menu primitive over the same channel:

Express — DTMF branch

app.post("/voice/outbound-answer", (req, res) => {
  // …signature checks as above…
  res.json({
    verbs: [
      { verb: "say", text: "Press 1 to confirm the appointment, or 2 to reach an agent." },
      {
        verb: "gather",
        input: ["digits"],
        numDigits: 1,
        timeout: 8,
        actionHook: "https://app.example.com/voice/appointment-choice",
      },
    ],
  });
});

app.post("/voice/appointment-choice", (req, res) => {
  // …same signature check; the body carries the pressed digit(s)…
  const digits = req.body.digits ?? "";
  if (digits === "1") {
    return res.json({
      verbs: [
        { verb: "say", text: "Confirmed. Thank you." },
        { verb: "hangup", reason: "Appointment confirmed" },
      ],
    });
  }
  return res.json({
    verbs: [
      { verb: "dial", callerId: "+16572262362", timeout: 30, target: [{ type: "phone", number: "+14155550199" }] },
      { verb: "hangup" },
    ],
  });
});

The full surface — gather with speech input, record (single-file capture with its own consent obligations), enqueue, transfer, listen (fork the live audio to a WebSocket for transcription or a voice agent), and the reserved conference / config verbs — is documented verb by verb in the DSL reference.

4. Track progress

Every call moves through ringing → in_progress → a terminal completed or failed (a ring that never answers ends as no-answer, reported in the same terminal stream). Poll the call record…

cURL

curl https://api.orbit.devotel.io/api/v1/voice/calls/call_9f2a1c \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node SDK

const { data: call } = await orbit.voice.calls.get("call_9f2a1c");
// call.status — ringing | in_progress | completed | failed

…or — in production — subscribe to the terminal events. Create a webhook endpoint in Settings → Webhooks, select call.completed and call.failed, and verify the delivery signature before trusting the body. Each event carries the call handle, direction, final status, duration, and the machine-readable cause (hangup_reason + the SIP code); your metadata from step 2 is echoed back so you can correlate straight to your own record:

{
  "type": "call.completed",
  "data": {
    "call_id": "call_9f2a1c",
    "status": "completed",
    "duration_seconds": 86,
    "metadata": { "order_id": "ord_8842" }
  }
}

5. Fetch the recording and the transcript

Pass record: true at create time and the call’s media lands as a recording once the call is terminal. Subscribe to recording.completed instead of polling; when the event lands the download URL on the call row is ready:

cURL — recording metadata + signed download URL

curl https://api.orbit.devotel.io/api/v1/voice/recordings?call_id=call_9f2a1c \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

curl https://api.orbit.devotel.io/api/v1/voice/recordings/rec_45de/download-url \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node SDK — finalized transcript

const { data: transcript } = await orbit.voice.transcripts.get("call_9f2a1c");
// GET /api/v1/voice/calls/{id}/transcript

Python SDK

transcript = client.request("GET", "/voice/calls/call_9f2a1c/transcript")

For a call you want to read as it happens, GET /api/v1/voice/calls/{callId}/transcript/stream streams partial and final transcript frames over SSE for the life of the call — one SDK call in Node:

Node SDK — live transcript stream

const handle = orbit.voice.calls.streamTranscript("call_9f2a1c", {
  onPartial: (frame) => process.stdout.write(frame.text),
  onFinal: (frame) => console.log("\nfinal:", frame.text),
  onError: (err) => console.error(err),
});
// handle.close() to tear down.

6. Production guardrails

Concurrency. Pace outbound originations per number and per API key — watch live usage and headroom in the API rate limits & quotas console and hold your originator below it; a 429 is the limiter telling you it is already over.
Voicemail detection. amd: true at create time asks the carrier to flag machine pickups — treat an AMD-flagged answer as a distinct branch (different prompt or a scheduled retry), never as a human-answered call.
STIR/SHAKEN. Devotel signs every outbound leg; what you own is the attestation policy, branded calling, and CNAM — see STIR/SHAKEN attestation.
Recording consent. Route-level capture and the DSL record verb have different consent gates — read the warning in the DSL reference before you turn either on.
Fallback is your seatbelt. Pick an explicit answer_fallback per call instead of inheriting safe-default silently — a flow with no fallback story is a flow that apologizes to your callees when your handler hiccups.

7. Failure modes

Terminal failures surface through call.failed and on the call record. Map the common ones:

Outcome	`status`	Typical `hangup_reason`	What to do
No answer	`no-answer`	`no_user_response` (SIP 480)	Retry on a schedule you own, or leave it.
Busy	`failed`	`user_busy` (SIP 486)	Redial later — the callee declined or was on another call.
Unreachable / invalid destination	`failed`	SIP 404/503/604, network error	Clean the number out of your dial list — retries burn spend.
answer_url failed	(fallback drives the call)	—	A `safe-default`/`voicemail`/`decline` fallback means the call still gets a sane path — ship it.

Consume these from the webhook events and let them feed disposition codes back into your list — the same signal the outbound dialer campaign surface paces with.

8. Next steps

Visual IVR for the inbound side — when the same verb logic should be authored, validated, and versioned without JSON, rebuild it in the IVR builder.
Outbound at scale — when you graduate from one-off calls to a paced dial list with disposition codes, move to the outbound dialer campaign surface.

The reference material this guide stood on: the Programmable Voice DSL reference, the OpenAPI spec for POST /api/v1/voice/calls, and the recipe collection in API recipes.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Program an outbound voice call: answer_url, verbs, and transcript

Program an outbound voice call

1. Provision a voice-capable number

2. Place the call

3. Implement the answer_url handler

4. Track progress

5. Fetch the recording and the transcript

6. Production guardrails

7. Failure modes

8. Next steps

​Program an outbound voice call

​1. Provision a voice-capable number

​2. Place the call

​3. Implement the answer_url handler

​4. Track progress

​5. Fetch the recording and the transcript

​6. Production guardrails

​7. Failure modes

​8. Next steps

Program an outbound voice call

1. Provision a voice-capable number

2. Place the call

3. Implement the answer_url handler

4. Track progress

5. Fetch the recording and the transcript

6. Production guardrails

7. Failure modes

8. Next steps