Start a call
POST/api/v1/click2call
Places one call: the platform connects the agent leg first and, once it
answers, dials the destination number (the customer leg) and bridges the
two. The agent leg is one of your SIP accounts by default, or your own
WebSocket endpoint with a_type: stream.
The response is the call resource in its initial accepted state. Poll
GET /api/v1/click2call/{id} for progress.
a_type: streamrequires an endpoint that speaks the didlogic WebSocket call protocol.
States
accepted → agent_ringing → agent_answered → customer_ringing →
bridged → completed, with failed reachable from any of them.
agent_ringingis not guaranteed. It is derived from a ringing indication on the agent leg, which some user agents never send, so it may be skipped entirely — a call can go straight fromacceptedtoagent_answered. Do not requireagent_ringingin client logic.
Webhooks
Pass callback_url and we POST a JSON body to it on every transition of the
call. It must be an https URL on a public host, at most 255 characters;
anything else is refused with 422 and no call is placed. Delivery is per
call — there is no per-account setting, and calls placed without the field
get no webhooks.
| Event | Fires when |
|---|---|
click2call.agent_ringing | the agent leg starts ringing |
click2call.agent_answered | the agent leg answers |
click2call.customer_ringing | the destination is dialled |
click2call.bridged | the two legs are bridged |
click2call.completed | the call ends normally |
click2call.failed | the call ends any other way |
click2call.finalized | the billed record is committed |
The body is {"event": …, "occurred_at": …, "event_seq": …, "data": {…}},
where data is the same call resource this endpoint returns. New fields may
appear in data and new names in the click2call.* namespace at any time:
ignore what you do not recognise.
click2call.completedand.failedfire immediately, withcoststillnull.click2call.finalizedfollows once billing has settled and carries the priced document. The two can arrive out of order —.finalizeddoes not mean nothing more is coming. Order is recoverable only fromevent_seq, which increases within a call.
Requests are not signed. Treat the call id as unguessable, not as proof
of origin, and confirm anything that matters with
GET /api/v1/click2call/{id}.
Delivery. Answer 2xx within 15 seconds. A 408, 429, 5xx or a
transport failure is retried up to five times with exponential backoff from
30 seconds, honouring Retry-After; any other 4xx is treated as permanent
and never retried. Delivery is at-least-once, so the same event_seq can
arrive twice.
Recordings
recording_url is null until the call is settled, and stays null for a
call that was not recorded. It rides in the same data of every
click2call.* webhook, so click2call.finalized is where it first appears.
Default. recording_url is a signed S3 link valid for 1 hour. Each read
of the call (get_call_status) mints a fresh one. 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, 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.
Caller ID
While the agent's phone rings it shows the destination number as the
caller. Pass a_cli to show a number of your choice instead — for example
when your agents must not see where the call is going. It is an E.164
number of at most 15 digits, with or without the leading +; if the field
is present at all it must be one, and anything else — including null or
an empty string — is refused with 422 invalid_a_cli and no call is
placed, so the destination is never shown by accident. a_cli does not
change the caller ID the destination sees.
b_cli is not supported in v1: sending it is refused with 422 caller_id_unsupported and no call is placed. The caller ID presented on
the customer leg is the one configured for your account.
Refusals
403 means the account may not use this endpoint at all —
click2call_api_disabled or account_not_verified. 409 means the account
is in a state that forbids placing a call — account_suspended. 402 means
the call cannot be paid for — insufficient_funds. 422 means the request
itself was refused, and every violation is listed in error.details. In every
case no call is placed and nothing is charged.
data.id feeds get_call_status and hang_up_call. data.recording_url feeds download_recording_by_link.
Request
Responses
- 201
- 401
- 402
- 403
- 409
- 422
The call was placed. Poll the read operation for progress.
The API token is missing or incorrect. This endpoint answers 401; the rest of v1 answers 403 for the same refusal.
The account has no funds available — insufficient_funds. The request was well formed and permitted; it simply cannot be paid for. No call is placed.
The account may not use this endpoint: the request is refused with click2call_api_disabled or account_not_verified. No call is placed.
The account is in a state that forbids placing a call — account_suspended. The request itself was well formed and permitted; no call is placed.
The request failed validation. error.code is always validation_failed; each violation appears in error.details with its own code and the field it belongs to — caller_id_unsupported (b_cli is not supported in v1), a_type_unsupported, invalid_a_endpoint, invalid_stream_url, invalid_stream_token, unknown_sip_account, invalid_b_number, invalid_a_cli, callback_url_insecure, invalid_callback_url or invalid_client_call_id. No call is placed.