Skip to main content
A call is one attempt to reach one phone number with one agent. You create it with POST /v1/calls (or many at once with batches), and it has an id like call_6f1d2c9a8b7e4f3a2d1c0b9a that you keep.

​
Statuses

A call in a final status never changes again, and its webhook is sent exactly once when it gets there.
completed becomes final when the AI has finished analysing the call, usually within a minute of hanging up. If the analysis never arrives, the call is finalised 10 minutes after it ended, with outcome: null.

​
Reading a call

​
string
The call id.
​
string
One of the statuses above.
​
string
Why a call is waiting, was canceled or failed, in plain words. Only present when there is a reason.
​
string
While queued: the earliest time it will be tried again, when it is held (outside calling hours, recall gap, daily limit).
​
object
What you sent, echoed back. phone_number is normalised to E.164.
​
string | null
The batch it belongs to, if any.
​
boolean
true for a test call.
​
integer | null
Length of the conversation.
​
string | null
ISO-8601 UTC timestamps.
​
string | null
A temporary link to the recording, valid until recording_expires_at (24 hours). Read the call again for a fresh link.
​
object | null
What the agent learned. See Outcomes.

​
Canceling

POST /v1/calls/{id}/cancel cancels a call that is still queued. Once it is dialing it cannot be stopped; the request returns 409 call_not_cancelable with the current status.

​
Finding calls

GET /v1/calls lists calls newest first. Filter with:
  • external_id: every call for one of your records (the contact.external_id you sent).
  • batch_id: every call in a batch.
  • created_after: calls created after an ISO-8601 time.
See Pagination.

​
One call per number at a time

A number that already has a call waiting in the queue cannot get a second one: the request fails with 409 call_already_queued, and details.call_id is the call already waiting. Once that call has been dialled, you can queue another, subject to the limits.