Call lifecycle and status values

A call can move through dialing, dialed, initiated, ringing, and answered before ending; these ten status values describe the call lifecycle, while cancellation can set an otherwise failed or configuration-blocked record to canceled.

Updated Oct 24, 2026v1Review areas: engineering and product

Treat the stored status as the current state of the call and the ordered events array as its audit trail. Carrier events can arrive asynchronously, so consumers must tolerate repeated reads and should not assume that every intermediate state will be observed.

Call lifecycle from dialing to ended with blocked, failed, and canceled outcomes

Status reference

Status	Meaning	Terminal?
`dialing`	The request passed preflight and CallOnline is starting the dial operation.	No
`dialed`	The carrier accepted the dial request and returned call identifiers.	No
`initiated`	The carrier reported that the call was initiated.	No
`ringing`	The destination is being alerted.	No
`answered`	The destination answered and the connected call can proceed.	No
`ended`	The connected or attempted call has ended.	Yes
`canceled`	A cancel request ended the active CallOnline call.	Yes
`dial_failed`	Dialing or subsequent local bookkeeping failed; the carrier outcome may be ambiguous.	Not guaranteed. Reconcile saved identifiers and later carrier events; cancellation can also set `canceled`.
`compliance_blocked`	Product preflight rejected the call before dialing.	Yes
`configuration_error`	Required calling or usage-tracking configuration was unavailable before dialing.	Yes for carrier progression; cancellation can change it to `canceled`.

The normal path is not guaranteed to visit every non-terminal status. For example, a fast carrier update may make polling observe dialed and then answered without seeing initiated or ringing.

Do not stop tracking solely because a record says dial_failed. A carrier can accept the call before a later local write fails, and a delayed carrier event can subsequently update that record. Reconcile the call before deciding whether any retry is safe.

Status versus events

GET /v1/calls/{callId} returns:

{
  "call": {
    "id": "call_opaque_identifier",
    "status": "answered",
    "createdAt": "2026-07-14T14:30:00.000Z",
    "answeredAt": "2026-07-14T14:30:08.000Z",
    "endedAt": null,
    "errorCode": null,
    "errorMessage": null
  },
  "events": [
    { "eventType": "dial", "payload": {} },
    { "eventType": "dialed", "payload": {} },
    { "eventType": "call.answered", "payload": {} }
  ]
}

Use call.status for the current decision and preserve event IDs or delivery IDs for audit and deduplication. Event names can be carrier-oriented (call.answered) or product-oriented (dialed, configuration_error). Do not convert event strings into the call-status enum without an explicit mapping.

Cancellation behavior

Canceling a call returns canceled, including when its stored status is dial_failed or configuration_error. If the stored call is already ended, canceled, or compliance_blocked, the cancel endpoint returns the existing state with alreadyFinal: true. A missing call returns 404.

Recommended application mapping

Show dialing, dialed, initiated, and ringing as in progress.
Show answered as connected.
Show ended as finished.
Show canceled as stopped by request.
Send dial_failed, compliance_blocked, and configuration_error to an exception path that displays the supplied error or block details. Continue reconciliation for an ambiguous dial_failed outcome.

Do not label compliance_blocked as a transient carrier failure. It requires a policy or evidence correction, not an automatic retry.