Outbound calls with an AI voice agent

​

Prerequisites

• A voice agent. Create one in the dashboard or over the API and note its agent_id (looks like agt_abc123). The agent must not be archived.
• A caller-ID number you own or have claimed as a trial number, passed as from.
• An API key with voice scope.

​

Request schema

curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+14155551234",
    "agent_id": "agt_abc123"
  }'

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

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const call = await orbit.voice.calls.create({
  to: "+14155552671",
  from: "+14155551234",
  agent_id: "agt_abc123",
});

console.log(call.id);

​

Response

{
  "data": {
    "call_id": "call_7b3e9c2d",
    "status": "initiated",
    "direction": "outbound"
  },
  "meta": {
    "request_id": "req_8c3f…",
    "timestamp": "2026-08-27T09:14:03Z"
  }
}

​

The agent speaks first

​

Compliance runs before anything dials

• Quiet hours — tenant-configured recipient-local dialing windows are enforced when you opt your org in. Set orgTimezone on the request when your org’s default timezone doesn’t match. See the Compliance API for the tenant-owned quiet-hours configuration.
• Do-not-call and STOP — numbers on your do-not-call list, or that have opted out across any channel, are blocked.
• AI-voice consent — a synthesized or agent voice requires prior written consent on file for the destination. The consent-management surface records that consent.

​

Options for unattended calls

• Answering-machine detection — set amd: true so the agent only engages a live person and skips machines and voicemail. AMD resolves on the destination’s own carrier; see Limits and edge cases for what to expect on timeouts.
• Recording — set record: true to record the call. When your account requires a spoken recording announcement, it plays before recording starts; if the announcement can’t play, the call proceeds without being recorded rather than recording silently.

curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+14155551234",
    "agent_id": "agt_abc123",
    "amd": true,
    "record": true
  }'

​

Error matrix

​

Limits and edge cases

• AMD is downstream-dependent. The carrier on the destination’s network drives answering-machine detection, so amd: true never adds a usable signal on every carrier. Expect AMD to resolve to human / machine / machine_beep_detected / no_answer on the carrier’s own cadence; treat it as a branch signal and let the call timeout still decide the outcome. Campaigns use the AMD result to abandon or branch on call.hit_voicemail rather than waiting for the call to finish.
• Archived agent detection is exact at dispatch time. An agent_id archived between “create call” and “dial” still fails cleanly — the dispatch gate re-checks the status and rejects before any ring starts. That is what protects recall campaigns from dead endpoints.
• Call-list pacing. For any list larger than a handful of numbers, run a dialer campaign instead of placing calls one at a time. The campaign paces the dials against your configured calling window, throttles to your settings, and applies the same compliance gates per number. Per-call API dialing is for ad-hoc one-off outreach.
• Dispositions, not raw statuses, close a campaign loop. When you use a campaign, record each attempt’s outcome against Dialer dispositions so abandoned-by-AMD, no-answer, and completed calls are all countable on the same report. The Voice call lifecycle page explains how individual status vs. event data fits together.

​

Events that fire on outbound

​

Cross-references

• The state machine and the complete failure taxonomy: Voice call lifecycle
• Every call.* event’s payload schema: Webhook events reference
• Reporting outcomes for a dialer campaign: Dialer dispositions
• Tenant-owned quiet-hours and consent configuration: Compliance → Consent Management