Skip to content
SIP.IO
DocsStart free

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.

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.

Terminal window
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" }'
ParameterPurpose
destinationRequired. A phone number, or a user id (us_…) for an internal call.
user_id · device_id · extensionThe agent, by user, by one specific phone, or by extension. Not needed when the key is bound to one agent.
cidCaller ID to present. Must be a number the account is allowed to present.
auto_answeryes/no. By default the agent’s phone rings; yes asks it to answer on its own (a headset-ready agent).
when_busyrefuse to reject the click if the agent is already on a call. Otherwise their phone rings as call waiting.
wait_for_answeryes holds the reply until the agent answers or the click ends (at most 150 s).
lead_id · varsYour 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.

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.

Each CRM gets its own integration, managed under /v1/c2c-integrations:

  • A Click to Call key (ck_…) opens /v1/c2c and 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_answer applies when a click doesn’t say.

Every click reports how it came out on your webhooks:

EventWhen
c2c.answeredThe agent picked up and the customer leg is being dialed.
c2c.endedThe click finished, with its outcome (answered, busy, no answer, rejected, unreachable or failed).
errorMeaning
user_not_found · device_not_foundThe agent or phone isn’t in this account.
user_inactiveThe agent has been deactivated.
caller_busywhen_busy=refuse and the agent is already on a call.