Calling

​

Endpoints

​

Authentication and limits

​

Three ways to answer

​

Answer incoming calls with your own server

1. Register a webhook for the call event (or all): Create Webhook.
2. Take the calls away from FlowIQ: PATCH /v1/calling/settings with {"answered_by": "api"}. The FlowIQ inbox stops ringing and FlowIQ’s voice AI stops picking up. Calls still show in the customer’s chat. Switch back any time with "flowiq".
3. When a customer calls, your webhook receives kind: "call", call.event: "connect" and WhatsApp’s SDP offer in call.session.sdp.
4. Answer: create an SDP answer for that offer with your WebRTC stack and send it with Accept Call. Pre-accept first if you want the audio to flow the moment you accept.
5. The call runs between WhatsApp and your media server. Audio never passes through FlowIQ. End it with End Call; when either side hangs up you receive call.event: "terminate" with the duration.

// Express + any WebRTC stack (wrtc, mediasoup, LiveKit, Pion via a sidecar...)
app.post("/flowiq/webhook", async (req, res) => {
  res.sendStatus(200); // answer the webhook fast, then work
  const e = req.body;
  if (e.event_type !== "call" || e.kind !== "call") return;
  if (e.call.event === "connect" && e.call.direction === "inbound") {
    const sdpAnswer = await myMediaServer.answer(e.call.session.sdp); // your code
    await fetch("https://api.flowiq.live/v1/calls/accept", {
      method: "POST",
      headers: { Authorization: `Bearer ${process.env.FLOWIQ_API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({ call_id: e.call.id, sdp: sdpAnswer }),
    });
  }
  if (e.call.event === "terminate") myMediaServer.hangUp(e.call.id);
});

​

Stream the audio to your own voice agent

1. Point the number at your server: PATCH /v1/calling/settings with {"answered_by": "stream", "stream": {"url": "wss://agent.example.com/flowiq", "format": "pcm16_16k", "headers": {"Authorization": "Bearer …"}}}. Formats: pcm16_16k (default), pcm16_8k, pcm16_24k, mulaw_8k.
2. When a customer calls, FlowIQ connects to your URL (with your headers, plus X-Flowiq-Call-Id and X-Flowiq-Organization-Id), answers the call, and streams.
3. The socket speaks JSON, shaped like Twilio Media Streams, so a voice agent written for Twilio works with little change (with mulaw_8k, usually unchanged):

​

Call a customer

1. Check: Get Call Permission tells you whether you may call now (can_start_call) and how many requests and calls you have left.
2. Ask: within 24 hours of the customer writing to you, Request Call Permission sends them an Allow calls button. Outside that window, send an approved template that has a call permission request with Send Template. Their answer arrives on your webhook as kind: "call_permission".
3. Call: Start Call with your SDP offer. WhatsApp rings the customer; when they answer, your webhook gets call.event: "connect" with their SDP answer in call.session, and kind: "call_status" events track ringing, accepted and rejected.

​

Or use SIP

​

The call object

{
  "id": "wacid.HBgLMjc4MjAwMDAwMDAVAgARGBI2RjQ3QkU1RjA5Q0UyMkEzQjQA",
  "channel": "whatsapp",
  "direction": "inbound",
  "status": "completed",
  "answered_by": "api",
  "started_at": "2026-10-26T20:48:04.097Z",
  "answered_at": "2026-10-26T20:48:41.000Z",
  "ended_at": "2026-10-26T20:49:51.000Z",
  "duration_seconds": 70,
  "end_reason": "completed",
  "transcript": null,
  "has_recording": false,
  "recording_url": null,
  "contact": { "id": "9b8a7c6d-…", "whatsapp_id": "27820000000", "name": "Jane Doe" }
}