Get call status
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 — 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.
Recordings
recording_url is null until the call is settled, and stays null for a
call that was not recorded.
Default. recording_url is a signed S3 link valid for 1 hour, minted
fresh on each read. Once it has expired, fetch the file through
get_call_recording.
Permanent links. Enabled on request through your account manager or
support. recording_url becomes /api/v1/recordings/{user_id}/{token},
which needs no authentication and answers 302 to a signed URL valid for
5 minutes. It answers 404 when the recording is no longer retained or the
option is turned off, and 429 with Retry-After past the per-minute
download limit. Details: download_recording_by_link.
This link is the recording_url returned by start_call,
get_call_status and their click2call.* webhooks, and sent in the
call-recording webhook. Without permanent links enabled, recording_url
holds a temporary pre-signed URL; to fetch a recording after it expires,
use get_call_recording.
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 download_recording_by_link. See also: hang_up_call.
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.