Click to Call
Click to Call turns a phone number in your CRM, helpdesk or web app into a call. One request rings the agent first; when the agent picks up, SIP.IO dials the customer and connects the two.
The customer leg is placed as the agent: it gets that user’s caller ID, call limits and recording rules, exactly as if they had dialed from their own phone. So a click can never step outside the rules an admin set for that person.
The request
Section titled “The request”GET or POST /v1/c2c. Parameters can go in the query string, a JSON body or a form body, so a CRM that can only open a URL works too.
curl -X POST 'https://api.sip.io/v1/c2c' \ -H 'x-api-key: ck_…' -H 'content-type: application/json' \ -d '{ "destination": "+12025550123", "extension": "201", "lead_id": "crm-4711" }'| Parameter | Purpose |
|---|---|
destination | Required. A phone number, or a user id (us_…) for an internal call. |
user_id · device_id · extension | The agent, by user, by one specific phone, or by extension. Not needed when the key is bound to one agent. |
cid | Caller ID to present. Must be a number the account is allowed to present. |
auto_answer | yes/no. By default the agent’s phone rings; yes asks it to answer on its own (a headset-ready agent). |
when_busy | refuse to reject the click if the agent is already on a call. Otherwise their phone rings as call waiting. |
wait_for_answer | yes holds the reply until the agent answers or the click ends (at most 150 s). |
lead_id · vars | Your own reference and free-form variables, carried onto the call and its webhooks. |
The reply comes at once:
{ "ok": true, "data": { "callId": "…", "customerCallId": "…", "cid": "+12025550100" } }ok means the agent’s phones are ringing. With wait_for_answer=yes, the reply instead says answered: true, or returns 409 with busy, no_answer, rejected, unreachable or failed. The API never answers a placed click with a 408 or 5xx, because HTTP clients retry those and the agent would be rung twice.
Failover across the agent’s phones
Section titled “Failover across the agent’s phones”If the agent has several registered phones (desk phone, softphone, mobile app), they are rung in order. A phone that is offline or doesn’t answer hands over to the next, and only one call-log row is written for the click.
Integrations, keys and allowlists
Section titled “Integrations, keys and allowlists”Each CRM gets its own integration, managed under /v1/c2c-integrations:
- A Click to Call key (
ck_…) opens/v1/c2cand nothing else, so a key pasted into a CRM can’t read your call records or change your account. - A key can be bound to one agent, for a CRM that cannot name who is clicking.
- An IP allowlist (addresses, CIDR blocks or ranges, up to 50) and a per-key rate limit protect the endpoint.
- A key can be shown again or rotated from the integration; revoking it takes effect immediately.
- The integration’s default
auto_answerapplies when a click doesn’t say.
Outcome webhooks
Section titled “Outcome webhooks”Every click reports how it came out on your webhooks:
| Event | When |
|---|---|
c2c.answered | The agent picked up and the customer leg is being dialed. |
c2c.ended | The click finished, with its outcome (answered, busy, no answer, rejected, unreachable or failed). |
Errors
Section titled “Errors”error | Meaning |
|---|---|
user_not_found · device_not_found | The agent or phone isn’t in this account. |
user_inactive | The agent has been deactivated. |
caller_busy | when_busy=refuse and the agent is already on a call. |
Related
Section titled “Related”POST /v1/calls: the same engine for your own agent app, with auto-answer on by default.- Embedded Softphone: the browser phone the agent answers on.
- Live Call Control and Call Transfer: what to do once the call is up.