Telephony

Start an outbound agent call

Start an outbound call from one of your active managed numbers into an Omni agent. A valid Idempotency-Key is mandatory. PyAI never retries an ambiguous dispatch and never changes routes after answer; only a confirmed retryable pre-answer result may advance an approved route plan. Limited availability: returns 404 until outbound telephony is enabled for the deployment. Requires telephony:manage.

post/v1/telephony/calls

Request

  • Base URL: https://api.pyai.com
  • URL: https://api.pyai.com/v1/telephony/calls
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Headers

Idempotency-Keystring required

Required safe-retry key. Identical retries return the original call; a different body returns 409.

Request body

from_number_idstring required

Active managed-number ID to present as caller ID.

tostring required

Supported E.164 destination.

agent_idstring required

Omni agent that handles the connected call.

use_case'transactional' | 'support' | 'sales' | 'collections' | 'survey' required

Declared calling purpose. Determines consent, identity, CNAM, and policy gates.

routing_profile'quality_first' | 'balanced' | 'cost_optimized'

Example request

{
  "to": "+14155550123"
}

Response

Call accepted

objectstring
idstring
from_number_idstring
tostring
agent_idstring
use_case'transactional' | 'support' | 'sales' | 'collections' | 'survey'
routing_profile'quality_first' | 'balanced' | 'cost_optimized'
status'queued' | 'dispatching' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'canceled' | 'dispatch_unknown'
attempt_countinteger
max_attemptsinteger
failure_reason'network_unavailable' | 'congestion' | 'timeout' | 'no_answer' | 'busy' | 'rejected' | 'invalid_number' | 'identity_blocked' | 'compliance_blocked' | 'unknown' | 'null' nullable
created_atinteger

Unix ms.

updated_atinteger

Unix ms.

answered_atinteger nullable

Unix ms.

ended_atinteger nullable

Unix ms.

Example response

{
  "object": "telephony.call",
  "id": "tcall_...",
  "to": "+14155550123",
  "artifacts": {
    "usage": {
      "meter": "telephony.minutes"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.