Skip to main content

Place a Click2Call 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: stream requires an endpoint that speaks our protocol. The message shapes, the audio format and what answers the call are described in WebSocket Calls.

States​

accepted → agent_ringing → agent_answered → customer_ringing → bridged → completed, with failed reachable from any of them.

agent_ringing is best-effort. 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 from accepted to agent_answered. Do not require agent_ringing in 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.

EventFires when
click2call.agent_ringingthe agent leg starts ringing
click2call.agent_answeredthe agent leg answers
click2call.customer_ringingthe destination is dialled
click2call.bridgedthe two legs are bridged
click2call.completedthe call ends normally
click2call.failedthe call ends any other way
click2call.finalizedthe 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.completed and .failed fire immediately, with cost still null. click2call.finalized follows once billing has settled and carries the priced document. The two can arrive out of order — .finalized does not mean nothing more is coming. Order is recoverable only from event_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.

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 click2call_show and click2call_destroy. data.recording_url feeds recordings_show.

Request​

Responses​

The call was placed. Poll the read operation for progress.