Click-to-Call Integration Guide

Overview — two ways to place a call

There are two integration models. We recommend the Browser Softphone flow — it needs the least from your side and gives agents the richest experience. A Server-to-Server option is available if your agents use real desk or mobile phones instead.

	Browser Softphone Recommended	Server-to-Server Alternative
Agent's phone	Runs in the browser — no physical phone	Real mobile / desk phone
Your integration	Point your Dial button at a URL	Your backend calls our REST API
Effort on your side	A URL template with 4 values	A small backend HTTP client
Mid-call transfer / 3-way	Built in	Via API

Browser Softphone flow

Your agent's Dial button opens a URL we provide — a plain link, not custom code. Everything else (registering the agent's softphone, dialing, bridging) happens automatically on our side.

The link your Dial button opens

https://api.clouddialer.in/CRM_API/webphone/launch
    ?crm_username = <your agent's ID>
    &api_key      = <integration key, provided at onboarding>
    &to_number    = <customer's number>
    &from_number  = <caller ID — one of your assigned numbers>

Most CRM platforms support this as a "click-to-call URL" or "CTI URL" setting — an admin pastes the template once, and the CRM substitutes the agent ID and customer number on each click. No custom code required.

Parameter	Value	Changes per…
`crm_username`	Your own stable ID for the agent (registered with us at onboarding)	Agent
`api_key`	One key for your whole integration, provided at onboarding	Never (rotatable on request)
`to_number`	The customer's number from the CRM record	Every click
`from_number`	Caller ID shown to the customer — any of the numbers assigned to your account. Use one or several; your choice per call.	Per call / campaign

What we provide

The launch URL template above
Your integration key
One or more caller-ID numbers assigned to your account
Registration of each agent ID you send us
Call recordings & status callbacks

What we need from you

A stable, unique ID per agent
A Dial button that can open a URL
The customer number available for substitution
A callback URL to receive call results (optional but recommended)

Call architecture

What happens between the click and two people talking:

sequenceDiagram participant Agent as Agent's Browser participant Platform as Our Platform participant Cust as Customer's Phone Agent->>Platform: Dial button opens launch URL Platform->>Platform: Identify agent, start their softphone Note over Agent: Softphone connects silently — nothing to click Platform->>Agent: Ring softphone (auto-answers) Platform->>Cust: Ring customer Cust-->>Platform: Answers Note over Agent,Cust: Bridged — live conversation Agent-->>Platform: Either side hangs up Platform-->>Agent: Call ends on both sides Platform->>Platform: Status + recording finalized

1Agent clicks Dial
Your CRM opens the launch URL with the agent's ID and the customer's number.
2Softphone starts automatically
We identify the agent and bring their browser softphone online — silently, with nothing for the agent to click or log into.
3We place the call
The agent's softphone answers itself, then the customer's phone rings.
4Bridged
Agent and customer are on a live call. A second number can be added mid-call for a warm transfer or three-way.
5Call ends
Either side hanging up ends the call for both. Status, duration, and the recording link are delivered to your callback URL.

Server-to-Server flow

If your agents use real phones, your backend can place calls directly — no browser involved:

POST https://api.clouddialer.in/calls
Authorization: Bearer <your API key>
Content-Type: application/json

{
  "from_number": "<one of your assigned caller-ID numbers>",
  "to_number":   "9876543210",
  "agent_number": "<agent's real phone number>",
  "uuid":        "your-own-call-id"
}

We ring the agent's phone first; once they answer, we ring the customer and bridge the two. The same endpoint also accepts crm_username in place of agent_number to route to a browser softphone instead — full details in the API Reference.

Call result push (callback)

Every call's outcome is stored on our side and then pushed to you — you don't need to poll. The moment a call ends, we send its complete record to a callback URL you provide.

What you provide

Item	Details
Callback URL	One HTTPS endpoint on your side that accepts a `POST`. Give it to us during onboarding — that's the only requirement to start receiving results.
Auth (optional)	If your endpoint needs authentication, tell us the header/token to include and we'll send it on every request.
Response	Return any `2xx` to acknowledge. A non-2xx (or a timeout) is treated as a failed delivery and retried.

How we push

Method	`POST` to your callback URL
Content-Type	`application/json`
When	Once, as soon as the call ends (any outcome — answered, no-answer, busy, failed)
Timeout	10 seconds for your endpoint to respond
Retries	Up to 3 attempts with exponential backoff (1s, 2s, 4s). The same `uuid` is sent on every retry — de-duplicate on it.

Payload

POST <your callback URL>
Content-Type: application/json

{
  "call_id":         "5deb67aa-d54d-4536-9a25-a29813b3bddd",
  "uuid":            "your-own-call-id",
  "status":          "ANSWER",
  "duration":        150,
  "customer_number": "9876543210",
  "agent_number":    "9876543211",
  "crm_username":    "agent.017",
  "call_type":       "browser",
  "disposition":     "CRM_CALL",
  "direction":       "outbound",
  "start_time":      "2026-07-03T10:00:00Z",
  "end_time":        "2026-07-03T10:02:30Z",
  "recording_url":   "https://api.clouddialer.in/recordings/crm_….wav"
}

Field	Description
`call_id`	Our unique ID for the call.
`uuid`	The value you passed at initiation, echoed back unchanged — use it to match the result to the CRM record that started the call.
`status`	Final disposition: `ANSWER`, `NO_ANSWER`, `BUSY`, `FAILED`, or `CANCELED`.
`duration`	Talk time in seconds (0 if not answered).
`customer_number`	The number that was called.
`agent_number` / `crm_username`	The agent who handled the call (your own ID is echoed as `crm_username`).
`call_type`	`browser` (softphone) or `server` (server-to-server).
`disposition`	Call disposition. A default is applied unless you set one.
`recording_url`	Direct download link for the recording (present when recording is enabled).
`start_time` / `end_time`	ISO 8601 timestamps.

Onboarding checklist

Item	Details
Agent ID scheme	The field you'll send as `crm_username` — must be stable and unique per agent. Send us the list of agents to register.
Dial button capability	Confirm your platform can open a URL from the Dial button (Browser flow) or make outbound HTTPS calls (Server-to-Server flow).
Caller-ID numbers	How many numbers you need and how you want to use them (one for everything, or several — e.g. per campaign or team). Assigned during onboarding; you choose per call via `from_number`.
Callback URL	HTTPS endpoint on your side to receive call results.
Server IPs	Server-to-Server flow only — your backend's IPs, so we can restrict API access to them.
Expected volume	Rough concurrent-call estimate, so we size capacity.

Typical timeline: integration testing can begin the same week the agent list and numbers are confirmed.

Security

Two keys, two sensitivities. The Browser-flow key appears in agents' browser URLs — treat it as low-sensitivity and rotatable (we can rotate it any time on request). The Server-to-Server API key must stay in your backend only, never in browser-side code.
IP restriction. Server-to-Server API access can be locked to your servers' IP addresses.
Recordings. Recording links use unguessable per-call URLs. Treat any recording URL you receive as private data.
Transport. All traffic — API, softphone signaling, and audio — is encrypted (HTTPS / WSS / SRTP).

CRM Integration Guide