People Call API Overview

One API for a team member's calls with your customers: calls out and calls in, on WhatsApp or on a phone line (PSTN). You say where the customer is (channel) and how the team member talks (mode).

Call out (WhatsApp, VOIP)  → POST /v1/call/person → credentials → your app joins → the customer's WhatsApp rings
Call out (phone, DIRECT)   → POST /v1/call/person → the team member's phone rings → then the customer's → connected
Call in  (WhatsApp, VOIP)  → poll /updates every 2 s → a call rings → POST /:callId/accept → credentials → your app joins
Hang up                    → POST /:callId/end → the call ends for everyone

What Is Supported

Incoming WhatsApp calls are answered through the API (VOIP). Incoming phone (PSTN) calls are answered on the team member's phone.

The Basics

• Base URL: https://public.doubletick.io
• Authentication: your DoubleTick API key in the Authorization header, as it is, with no Bearer in front. A missing or wrong key gets 401.
• Content type: application/json.
• The team member is named by agentNumber: the phone number on their DoubleTick profile, with country code. It must match exactly one active team member of your organization. Every permission check is done for that team member, not for the API key's owner.
• Phone numbers take the country code, with or without a leading + (7–15 digits).
• One call at a time: a team member can be on one call at once.
• Unknown fields are refused ("<field>" is not allowed).

📘

NOTE

If you do not have your DoubleTick API Key, you can obtain it by following this guide link.

Reply Shape

{ "success": true, "message": "...", "data": { ...the call... }, "credentials": { ... } }

{ "status": 400, "reason": "MODE_NOT_SUPPORTED", "message": "..." }

• data is always the call, read fresh (see The call object). A call is the same object on every route.
• credentials come only on a VOIP call out, accept and reconnect (see Joining a VOIP call).

Endpoints

{callId} is the id from a reply, from /updates, or from your call webhooks. A call of another organization, or a call no team member is on (for example an AI agent's call), gets 404 Call not found.

Typical Flows

A team member calls a customer on WhatsApp

1. POST /v1/call/person {channel: WHATSAPP, mode: VOIP, from, to, agentNumber}
2. join with the credentials (see Joining a VOIP call) → the customer's WhatsApp rings
3. the customer answers → talking
4. POST /v1/call/person/{callId}/end → close the audio connection

A customer calls on WhatsApp and a team member answers

1. POST /v1/call/person/updates {agentNumber}, every 2 s → a call appears, callStatus INITIATED, callDirection INCOMING
2. POST /v1/call/person/{callId}/accept {agentNumber} → credentials
3. join with the credentials → talking (or POST …/decline to refuse it)
4. POST /v1/call/person/{callId}/end → close the audio connection

A team member calls a customer on a phone line

1. POST /v1/call/person {channel: PSTN, mode: DIRECT, from, to, agentNumber}
2. the team member's phone rings → they pick up → the customer is dialled → connected
3. either side hangs up, or POST /v1/call/person/{callId}/end

The Call Object (data)

Field names match the call webhooks you already receive; the callId is the same.

Joining a VOIP Call with the Credentials

A VOIP call out, accept and reconnect return credentials:

{
  "transport": "SIP",
  "wssUrl": "wss://...",
  "sipUri": "sip:...",
  "username": "...",
  "password": "...",
  "headers": { "...": "..." },
  "iceServers": [],
  "codecs": ["opus", "G722", "PCMU", "PCMA"],
  "expiresAt": "2026-10-26T10:00:30.000Z"
}

They open one voice session over a secure WebSocket, using the standard SIP-over-WebSocket protocol with WebRTC audio. Libraries such as JsSIP or SIP.js (browser and Node.js) and PJSIP (mobile and server) do this.

1. Open a WebSocket to wssUrl. Do not register.
2. Send one call (INVITE) to sipUri. Add every header in headers, and answer the login challenge with username and password.
3. Audio only. Offer the codecs in the order given, Opus first.
4. Use ICE with DTLS-SRTP and rtcp-mux, and the iceServers exactly as given (the list may be empty).
5. Send a keep-alive every 20–30 seconds while the call is up.
6. Turn on echo cancellation, noise suppression and automatic gain on the microphone (in a browser: getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true } })).

• Use them once, within 30 seconds (expiresAt). For a new session, call reconnect.
• One join at a time. A new join replaces the team member's current connection on the call.

🚧

Keep them secret

Never write credentials to a log.

Errors

Every error is { status, reason, message }. Some have no reason; use the HTTP status and the message. The errors below apply to every route; each endpoint's page lists its own.

Checked first, on every route

Rate Limits

• Limited replies carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 carries Retry-After.
• On top of these, every public route allows at most 100 requests a second from one IP address.

Moving from the Old Routes

The /whatsapp/call/* and /v1/call/create routes are for browser web calling and are being retired. On numbers where they are no longer available they answer 400 Calling is not supported on this number. Use /v1/call/person instead:

• The new routes send no SDP: your app joins with the returned credentials instead (see Joining a VOIP call).