API Reference

WhatsApp Call Public API

The WhatsApp Call Public API allows you to initiate, receive, accept, reject, and manage voice calls between your business and customers on WhatsApp.

This API works together with:

  • Call lifecycle webhooks
  • WebRTC SDP exchange
  • Call APIs

Base URL:
https://public.doubletick.io/whatsapp/call

All endpoints require Public API authentication and are subject to path-based rate limiting.

🔁 How the call system works (High Level)

At a high level, every WhatsApp call follows this flow:

  1. Call is initiated (incoming or outgoing)
  2. Webhook events notify you of call state changes
  3. SDP offer/answer is exchanged to establish audio
  4. Call is accepted / rejected / missed
  5. Call ends, recording & duration become available

📌

Important:

For both incoming and outgoing calls, all state changes are delivered via webhooks.
Always rely on webhooks to track call progress.

👉 Refer to the Call Webhooks documentation to understand how to consume these events.

🌐 Rate limits

PathWindowMax Requests
/create60s60
/accept60s60
/decline60s60
/reconnect60s60
/ping60s15
/settings60s10
/call-permissions1s1

If org or user context is unavailable, rate limits fall back to IP-based limiting.

📡 Webhooks are mandatory

This API is event-driven.

You will receive webhook events for:

  • Incoming calls
  • Outgoing call creation
  • Call accepted / rejected / missed
  • Call ended
  • Recording availability

You must subscribe to call webhooks to:

  • Know when to generate SDP
  • Know when a call is accepted
  • Track call duration and outcome

👉 See: Call Webhooks → Voice Call Events

🔊 Understanding SDP (Offer & Answer)

WhatsApp calls use WebRTC under the hood.
To establish audio between the client and WhatsApp, an SDP exchange is required.

What is SDP?

SDP (Session description protocol) is a text payload that describes:

  • Audio codecs (Opus, etc.)
  • Transport details (ICE, DTLS)
  • Media direction (send/receive)

SDP does not carry audio — it only negotiates how audio will flow.

SDP Offer

An SDP Offer is:

  • Generated by the caller
  • Describes “here’s how I can send/receive audio”

In this system:

  • For outgoing calls, you generate the SDP offer
  • For incoming calls, WhatsApp provides the SDP offer via webhook

SDP Answer

An SDP Answer is:

  • Generated by the receiver
  • Accepts or modifies the offer parameters

In this system:

  • When accepting a call, you send an SDP answer back via API
  • This completes media negotiation

🛠️ How to generate SDP

You generate SDP using WebRTC APIs in your client (browser, mobile, or desktop).

Example (Browser – WebRTC)

const pc = new RTCPeerConnection();

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
stream.getTracks().forEach(track => pc.addTrack(track, stream));

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

// offer.sdp → send this as SDP Offer

For answering a call:

await pc.setRemoteDescription({ type: 'offer', sdp: incomingSdp });

const answer = await pc.createAnswer();
await pc.setLocalDescription(answer);

// answer.sdp → send this as SDP Answer

📌

The API only expects the SDP string — media handling stays entirely on your side.

🔄 End-to-End call flow

📤 Outgoing call (Business → Customer)

  1. Create call using /create
  2. Generate SDP offer
  3. Send SDP offer in create request
  4. Receive webhook: CALL_OUTGOING_INITIATED
  5. Customer accepts → webhook CALL_ACCEPTED
  6. Call is connected
  7. Call ends → webhook CALL_ENDED

👉 See: Outbound Call API

📥 Incoming call (Customer → Business)

  1. Customer initiates call

  2. Receive webhook: CALL_INCOMING_INITIATED

    • Includes SDP offer

  3. Generate SDP answer

  4. Accept call using /accept

  5. Call connects

  6. Call ends → webhook CALL_ENDED

👉 See: Incoming Call API

🔐 Call permissions

WhatsApp requires explicit customer consent before allowing outbound calls.

Use the Call Permissions API to:

  • Request call permission
  • Check permission status
  • Handle permission expiry

Outbound calls will fail if permission is not granted.

👉 See: Call Permission API

📚 Documentation structure

  • Overview (this page) – Concepts & flow
  • Outbound Call API – Create & manage outbound calls
  • Incoming Call API – Accept, reject incoming calls
  • Call Permissions API – Customer consent management
  • Call Webhooks – All call lifecycle events