Skip to content
Developer docsChannel Automation Developers
First requestVisit website ↗
Navigation

Start a built-in Voice AI outbound call

Served by the standalone Voice API. Requires a Bearer session for a workspace owner/admin/manager when VOICE_AI_TELEPHONY_TURN_CONTROL_V2 is enabled. Legacy flag-off access is preserved. Internal callers may instead send X-Voice-Service-Time (Unix milliseconds) and X-Voice-Service-Signature (hex HMAC-SHA256). The signature binds the method, full route including workspace, and JSON body, and expires after 60 seconds. Every non-queue dial checks outbound enablement, workspace DNC/suppressions, phone opt-out and contact-local calling hours before the dial-cap claim or Twilio. Refusals return 409 refused_compliance; flow callers skip the step. AI queue calls keep their existing SQL compliance gate. Workspace lease capacity applies to both paths; the outbound share defaults to 70 percent and preserves at least one inbound slot when the total is two or more.

POST
https://api.channelautomation.com/api/workspaces/{workspaceId}/voice-ai/outbound-call

Authorization

  • BearerAuth
    HTTP Bearer (JWT)
    required

Path parameters

  • workspaceId
    string
    required

Header parameters

  • X-Voice-Service-Time
    optional
    string

    Required with service signature; Unix milliseconds.

  • X-Voice-Service-Signature
    optional
    string

    Service request HMAC; alternative to Bearer authentication.

Request body JSON

  • to
    optional
    string

    Required destination phone number.

  • from
    optional
    string

    Optional active workspace caller ID.

  • contact_id
    optional
    string

    Contact in this workspace; when omitted, resolve by destination phone.

    format: uuid
  • voice_agent_id
    optional
    string
    or null

    Explicit voice profile; otherwise the workspace default. Caller-ID assignments are inbound only. Unavailable explicit picks refuse before any lease or dial claim. VOICE_AGENT_ROUTING=default_only overrides picks and logs agent_fallback.

    format: uuid
  • idempotency_key
    optional
    string

    Stable run and node identity. Repeat requests return the existing request and CallSid without another dial. Omitted keys create independent requests.

    maxLength: 300
  • ai_queue_attempt_id
    optional
    string

    Internal AI queue attempt; requires matching contact_id and call_queue_id.

    format: uuid
  • context
    optional
    string

    Call context capped at 6000 characters.

  • firstMessage
    optional
    string

    Opening message capped at 220 characters.

Returns

200

Started or existing call, including request_id, call_sid and resolved_voice_agent_id (nullable). routing_mode=default_only and agent_fallback=true identify an infrastructure override.

202

Existing request has no confirmed CallSid yet. Do not create another request to retry an uncertain dial.

400

Invalid call or preview parameters

401

Missing or invalid session

403

Workspace owner/admin/manager required

404

Requested resource not found

409

Refused before dialing by compliance, voice_agent_unavailable, or the existing AI queue SQL gate
JSON
  • success
    optional
    boolean
  • status
    optional
    string
  • reason
    optional
    string

429

Workspace outbound capacity or per-contact AI dial cap reached

500

Operation failed

503

Access verification or service unavailable

Type to search…

↑↓ navigate↵ selectEsc close