API Reference

Start a call

Wire this to your Dial button. Open it in a new tab/window.

https://api.clouddialer.in/CRM_API/webphone/launch
  ?crm_username=<your agent id>
  &api_key=<your launch key>
  &to_number=<customer number>
  &from_number=<your caller-ID>

Conference / add a participant

Wire this to your Conference button. It adds the third party into the agent's existing call — everyone stays on together. It does not start a new call, and it does not open a second call window.

https://api.clouddialer.in/CRM_API/webphone/launch
  ?action=conference
  &to_number=<number to add>

No call_id, no API key, no backend call. The agent's open call tab picks it up and merges the party in.

Start a call

We ring the agent's phone first. Only once the agent answers do we dial the customer, and bridge them together. If the agent never picks up, the customer is never called.

Body

Example

POST /calls
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "from_number":   "<your caller-ID>",
  "to_number":     "9876543210",
  "agent_number":  "9812345678",
  "crm_username":  "agent.017",
  "uuid":          "550e8400-e29b-41d4-a716-446655440000",
  "recording":     true
}

200 OK
{ "status": "success", "call_id": "5deb67aa-…", "message": "Call initiated" }

Conference / add a participant

Merge a third party into the agent's current call. Identify the agent exactly as you did when dialing — we resolve their live call ourselves, so you never need to store our call_id.

POST /calls/conference
Authorization: Bearer <your-api-key>

{ "crm_username": "agent.017", "number": "9811111111" }

200 OK
{ "status": "success", "message": "Conference leg queued",
  "call_id": "5deb67aa-…", "leg_id": 3 }

If the added party doesn't answer, the existing call is unaffected.

Live agents

Every call in progress for your account — who is on a call, with whom, and each party's state. Useful for a real-time supervisor view.

200 OK
{
  "status": "success",
  "count": 1,
  "calls": [{
    "call_id": "5deb67aa-…",
    "uuid": "your-own-call-id",
    "crm_username": "agent.017",
    "agent_number": "9812345678",
    "customer_number": "9876543210",
    "call_status": "ANSWER",
    "call_type": "server",
    "started_at": "2026-07-03T10:00:00Z",
    "legs": [
      { "role": "agent",       "number": "9812345678", "status": "JOINED" },
      { "role": "destination", "number": "9876543210", "status": "JOINED" }
    ]
  }]
}

Call status

Poll one call's status, duration, recording URL and per-party detail. Optional — the result push covers the normal flow.

call_status is one of INITIATED, ANSWER, NO_ANSWER, BUSY, FAILED, CANCELED. Each leg is DIALING, JOINED, LEFT, or FAILED.

Add a participant by call_id

Same as /calls/conference, but identified by our call_id instead of the agent. Use this only if you already store the call_id; otherwise prefer /calls/conference.

{ "number": "9811111111" }

Call result push

When a call ends we POST the full result to the callback URL you give us during onboarding. You don't poll. Up to 3 retries; de-duplicate on uuid. Full field list in the Integration Guide.

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

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

call_type tells you which integration produced the call: browser or server.

This event waits until the recording has been verified on disk, so it lands roughly ten seconds after the call ends. recording_url is optional and absent when there is no verified recording — that means "no recording exists", not "retry later". For something that fires the instant the call ends, see below.

Instant hangup event

Sent the moment either side hangs up — before any recording work, so nothing delays it. This is what a post-call form should open on.

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

{
  "event": "call_hangup",
  "call_id": "5deb67aa-…", "uuid": "your-own-call-id",
  "status": "ANSWER", "duration": 150,
  "customer_number": "9876543210", "agent_number": "9876543211",
  "from_number": "8047587340", "crm_username": "agent.017",
  "direction": "outbound",
  "start_time": "2026-07-03T10:00:00Z", "end_time": "2026-07-03T10:02:30Z"
}

It carries no recording_url — that is exactly why it is immediate. The verified recording still arrives in the call result push above, so a call you have both enabled for produces two events. Ordering between them is not guaranteed; de-duplicate on uuid and handle whichever lands first.

failure_reason is added when a call failed for a known reason — currently agent_unreachable, meaning the agent never answered and the customer was never dialled.

Live call events (SSE)

Your page holds one connection open and we push every state change to it as it happens — ringing, answered, the running call timer, and the hangup. There is no endpoint for you to host and nothing to poll.

Which stream to open

Agent stream

Reports whatever call that agent is on. Every state change arrives as one event name, call_update; read live and answered to tell which transition it is.

const es = new EventSource(
  `https://api.clouddialer.in/crm-agent-stream?key=${LAUNCH_KEY}&crm_username=${AGENT}`
);

es.addEventListener('call_update', e => {
  const call = JSON.parse(e.data);
  if (!call.live)      showEnded(call.status, call.duration, call.recording_url);
  else if (call.answered) showConnected(call.customer_number);
  else                 showRinging(call.customer_number);
});

// live timer — once a second while the call is up
es.addEventListener('call_tick', e => showDuration(JSON.parse(e.data).elapsed));

Calls that started before you connected are ignored, so open the stream when the page loads rather than on click.

Call-id stream

You choose the uuid and pass it when you start the call, so you can subscribe before the call exists and miss nothing. Each transition gets its own event name.

const es = new EventSource(
  `https://api.clouddialer.in/crm-uuid-stream?key=${LAUNCH_KEY}&uuid=${myCallId}`
);

es.addEventListener('call_ringing',  e => showRinging(JSON.parse(e.data)));
es.addEventListener('call_answered', e => showConnected(JSON.parse(e.data)));
es.addEventListener('call_hangup',   e => showEnded(JSON.parse(e.data)));
es.addEventListener('call_tick',     e => showDuration(JSON.parse(e.data).elapsed));

Reconnecting is safe. A page refresh, a dropped connection or a browser tab restored later can simply reopen the stream with the same uuid, and we replay where the call currently stands:

Per-call stream

Emits call_state once on connect, then call_hangup, after which the server closes the stream. Useful only where you already hold the call_id.

Events

Event fields

No delivery guarantee. A closed tab, a sleeping laptop or a dropped connection means the event is missed, and unlike the callback there is nowhere to retry to. Anything that must not be lost belongs on the callback.

Authentication is by query parameter because the browser EventSource API cannot set an Authorization header. Pass your launch key — never the vendor API key, which is a backend credential and would end up in browser history and access logs. A keepalive comment is sent periodically so proxies do not close an idle connection; EventSource never surfaces those. If streaming is not yet active on your account the endpoint returns 403 SSE_DISABLED — contact us and we will switch it on.

Download a recording

Direct download using the exact URL from the result push. The unguessable per-call filename is the access control — treat recording URLs as private. Returns the audio file, or 404.

Health check

Unauthenticated liveness check for your monitoring.

200 OK
{ "status": "success" }