Calls
Place outbound calls, end active ones, and retrieve call records with transcripts and recordings.
The call object
json
{
"id": "call_abc123",
"object": "call",
"agent_id": "agent_xyz789",
"direction": "outbound",
"phone_number": "+14155551234",
"caller_id": "+14155558888",
"status": "in_progress",
"started_at": 1712345678,
"ended_at": null,
"duration": null,
"transcript_id": null,
"recording_url": null,
"context": {"customer_name": "Jane"},
"metadata": {"campaign": "spring-reminders"}
}Create a call (outbound)
POST/v1/agents/{agent_id}/calls
phone_numberstringRequired
E.164 destination. +14155551234.
contextobjectOptional
Variables injected into the system prompt.
max_durationintegerOptional
Cap on call length in seconds. Default 1800 (30 minutes).
recordbooleanOptional
Save audio. Default false.
caller_idstringOptional
Override the caller id. Must be a number approved on the account.
idempotency_keystringOptional
Set via the Idempotency-Key header, not the body. See API overview.
Retrieve a call
GET/v1/calls/{call_id}
End a call
POST/v1/calls/{call_id}/end
Force-end an active call. No-op on completed calls.
Call status values
| Status | Meaning |
|---|---|
initiating | Object created, media leg starting. |
ringing | Far side is ringing. |
in_progress | Call answered; agent is running. |
completed | Call ended normally. |
failed | Technical failure. See call.error. |
no_answer | Rang through without answer. |