Read a Click2Call call
GET/api/v1/click2call/:id
Returns the current state of one call. This is the polling endpoint: call it
until state is completed or failed.
States
| State | Meaning |
|---|---|
accepted | The call was placed; no leg has moved yet |
agent_ringing | Your SIP account is ringing — best-effort, may be skipped |
agent_answered | Your SIP account answered |
customer_ringing | The destination is being dialled |
bridged | Both legs are up and talking |
completed | The call ended normally |
failed | The call did not come together |
agent_ringing is derived from a ringing indication on the agent leg, which
some user agents never send. A call may therefore go straight from
accepted to agent_answered; clients must not require agent_ringing.
reason
reason answers why the call ended, on its own axis from state. It is
null while the call is live and on a normal end. Otherwise it is one
of no_answer, busy, unreachable, canceled, timed_out or
platform_error. A call your own DELETE ended reports canceled —
including when it had already been answered, in which case state is
completed. A DELETE that arrives after the call has already ended leaves
the original reason in place.
Retention
A call is readable for 12 hours from the moment it was placed — not from
the moment it ended. After that the record is gone and this endpoint answers
404. Call history is a separate product surface.
404
404 call_not_found means the call is unknown to you: it never existed, the
ID is malformed, it belongs to another account, or it has fallen out of the
12-hour window. The cases are deliberately indistinguishable.
data.recording_url feeds recordings_show. See also: click2call_destroy.
Request
Responses
- 200
- 401
- 403
- 404
The current state of the call.
The API token is missing or incorrect. This endpoint answers 401; the rest of v1 answers 403 for the same refusal.
The API token is missing or incorrect, or the Click2Call API is not enabled for this account (click2call_api_disabled).
No such call: it never existed, the ID is malformed, it belongs to another account, or it is older than the 12-hour retention window.