callStatus Reference
body.data.callStatus carries the snapshot of the call's state at the moment of notification. This page lists all possible values, what they mean, and how they relate to eventType.
Do not use callStatus to detect errors. Transitional statuses such as CALLING may appear even when an error occurred. Detect errors via the body.errors array (see Payload Spec > body.errors).
Outbound call status
| callStatus | Meaning | Corresponding eventType |
|---|---|---|
PENDING | Just queued for outbound dialing | OUTBOUND_CALL_PENDING |
REQUESTED | Dial instruction issued to the telephony provider | OUTBOUND_CALL_REQUESTED |
CALLING | Ringing the recipient / call being established | OUTBOUND_CALL_CALLING |
CLOSING | Post-call wrap-up after disconnection | OUTBOUND_CALL_CLOSING |
COMPLETED | Call completed normally (if errors is non-empty, completed with errors) | OUTBOUND_CALL_COMPLETED |
EXPIRED | Scheduled outbound dial window exceeded | OUTBOUND_CALL_EXPIRED |
NO_RESPONSE | The recipient did not answer | OUTBOUND_CALL_NO_RESPONSE |
CANCELED | Canceled from PENDING by a user action | OUTBOUND_CALL_CANCELED |
BUSY | The recipient's line was busy | OUTBOUND_CALL_BUSY |
UNREACHABLE | Could not reach the recipient (out of service area, powered off, etc.) | OUTBOUND_CALL_UNREACHABLE |
MAX_ATTEMPTS_REACHED | Redial attempt count, including retries, hit its upper limit | OUTBOUND_CALL_MAX_ATTEMPTS_REACHED |
ERROR | An error occurred | OUTBOUND_CALL_ERROR |
VOICEMAIL_REACHED | Reached voicemail | OUTBOUND_CALL_ERROR family (internal categorization) |
HEALTHCHECK_FAILED | Healthcheck failed | OUTBOUND_CALL_ERROR family (internal categorization) |
LIMIT_REACHED | Various internal limit reached | Consolidated into OUTBOUND_CALL_ERROR |
CONNECTING | Internal connecting state | Consolidated into OUTBOUND_CALL_ERROR |
CONCURRENCY_LIMIT_EXCEEDED | Internal concurrency limit exceeded | Consolidated into OUTBOUND_CALL_ERROR |
LIMIT_REACHED / CONNECTING / CONCURRENCY_LIMIT_EXCEEDED may appear in callStatus as internal states, but no separate Webhook event is fired for them — they are surfaced externally as OUTBOUND_CALL_ERROR.
Inbound call status
| callStatus | Meaning | Corresponding eventType |
|---|---|---|
CONNECTING | Inbound call received, internal processing started | INBOUND_CALL_CONNECTING |
CALLING | Call established, conversation in progress | INBOUND_CALL_CALLING |
CLOSING | Post-call wrap-up after disconnection | INBOUND_CALL_CLOSING |
COMPLETED | Call completed | INBOUND_CALL_COMPLETED |
CONCURRENCY_LIMIT_EXCEEDED | Concurrent-call limit reached | INBOUND_CALL_CONCURRENCY_LIMIT_EXCEEDED |
ERROR | An error occurred | INBOUND_CALL_ERROR |
Relationship between eventType and callStatus
The two are related but distinct:
eventType= the Webhook delivery trigger name (the publicly exposed signal)callStatus= the internal state of the call (a data field within the payload)
They map almost one-to-one, but several internal statuses are consolidated into one externally exposed event (e.g. LIMIT_REACHED → OUTBOUND_CALL_ERROR as shown above).
We recommend using eventType as the primary switch key on the receiver side. callStatus is better suited to supplementary logic, logging, and statistics.
State transitions (conceptual)
OUTBOUND
PENDING → REQUESTED → CALLING → CLOSING → COMPLETED
↘ NO_RESPONSE / BUSY / UNREACHABLE / EXPIRED / ...
↘ ERROR
CANCELED ← (user action from PENDING)
INBOUND
CONNECTING → CALLING → CLOSING → COMPLETED
↘ CONCURRENCY_LIMIT_EXCEEDED
↘ ERROR
The detailed transition specification depends on internal implementation. What is guaranteed externally is FIFO delivery of events for the same callId (see Setup Guide > Delivery behavior).