Skip to main content

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​

StateMeaning
acceptedThe call was placed; no leg has moved yet
agent_ringingYour SIP account is ringing — may be skipped
agent_answeredYour SIP account answered
customer_ringingThe destination is being dialled
bridgedBoth legs are up and talking
completedThe call ended normally
failedThe 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​

The current state of the call.