API documentation

Overview

FluxRelay exposes a small bearer-authenticated HTTP API on top of your connected WhatsApp sessions. The public API is intentionally separate from the dashboard session endpoints.

Recommended workflow

• Add and connect a sender from the Devices page.
• Keep the API key private and use it only from trusted server-side workflows.
• Submit messages with the sender number, recipient number and message body.
• Use device-status to inspect runtime health before critical workflows.

Authentication

All public /api/* endpoints require your account API key. Send it as a bearer token.

Authorization: Bearer gw_live_...

Regenerating the key immediately invalidates the previous key. Do not expose it in browser code, public repositories, screenshots or client-side apps.

Phone number format

Use international digits only, including the country code. Do not include +, spaces, brackets or hyphens.

The current gateway validates sender and recipient as 8–15 digits for the send-message endpoint.

Send text message

cURL

JavaScript

Success response

{
  "status": true,
  "accepted": true,
  "sender": "923001234567",
  "recipient": "923009876543",
  "message": "Message submitted to WhatsApp successfully.",
  "receipt_available": false,
  "connection_status": "Connected",
  "data": null
}

Check number

This endpoint calls the underlying WhatsApp existence check. Treat it as informational only; the current Baileys build can produce false negatives, so send-message does not block on this result.

List devices

Returns the senders owned by the API-key account plus runtime connection metadata.

Useful fields

Single device status

Use this before a critical send if your workflow needs to know the gateway's current runtime view of a sender.

n8n HTTP Request node

Create an HTTP Request node and configure it as below. Keep the bearer key in an n8n credential or environment secret rather than hardcoding it in a workflow you plan to share.

Suggested production flow

Validate the customer number → build the message → call the gateway → inspect status/accepted → log the response. Do not blindly retry a send after an ambiguous network failure because that can create duplicate customer messages.

Response semantics

WhatsApp delivery and read status are separate concepts and are not currently exposed by this public API.

Error handling

For a 502, inspect the sender's device status. The gateway intentionally does not auto-resend the failed message because automatic resend could duplicate messages when the upstream result is ambiguous.

Security checklist

• Regenerate any API key that appears in chat logs, screenshots or public code.
• Call the API from backend systems such as n8n, not from public client-side JavaScript.
• Use HTTPS only.
• Give each customer/tenant their own gateway account or API key boundary when practical.
• Do not expose the legacy /backend-* endpoints publicly to untrusted clients.
• Use the service only for recipients you are authorized to message and comply with WhatsApp rules and applicable law.

Send interactive buttons

This endpoint uses WhatsApp Native Flow interactive messages instead of the deprecated legacy button payload.

cURL

Button shapes

{ "type": "reply", "text": "Yes", "id": "yes" }
{ "type": "url",   "text": "Open site", "url": "https://example.com" }
{ "type": "call",  "text": "Call us", "phone": "923001234567" }
{ "type": "copy",  "text": "Copy code", "copy": "SAVE20" }

Quick-reply button webhooks

When a customer taps a reply button, the linked WhatsApp session receives an interactive response. V3.5 detects that response and POSTs a normalized event to the webhook URL configured on the sender device.

Webhook payload

{
  "event": "button.clicked",
  "event_id": "evt_...",
  "timestamp": "2026-09-26T17:00:00.000Z",
  "device": "923233200938",
  "from": "92300XXXXXXX",
  "button": {
    "id": "continue",
    "text": "Yes, Continue",
    "kind": "native_flow"
  },
  "message": {
    "id": "3EB0...",
    "chat_jid": "92300XXXXXXX@s.whatsapp.net"
  }
}

n8n receiver

Create an n8n Webhook node using POST, copy its production URL into Devices → Webhook, then branch on {{$json.event}} and {{$json.button.id}}.

Message history

Returns recent outbound sends and inbound quick-reply events for the API-key account. The Activity page uses the same storage.

Delivery & read tracking

Tracked sends return a message_id and tracking_url. Query the tracking endpoint for the latest receipt state.

{
  "status": true,
  "tracking": {
    "message_id": "3EB0...",
    "last_status": "delivered",
    "sent_at": "...",
    "delivered_at": "...",
    "read_at": null,
    "expires_at": null,
    "expired_at": null
  }
}

Expiring Copy button

Add expires_in_seconds (30 seconds to 30 days) to an interactive request containing a Copy button.

{
  "sender":"923233200938",
  "recipient":"923009876543",
  "message":"Your coupon is ready",
  "buttons":[{"type":"copy","text":"Copy code","copy":"SAVE20"}],
  "expires_in_seconds":300,
  "expired_message":"This coupon has expired."
}

At expiry the gateway deletes the original interactive message and sends a replacement without the Copy button. This is a replacement workflow, not an in-place edit.

Support Inbox API

Incoming customer messages are captured from the live linked-device socket and can also be delivered to the device webhook as message.received events.

Legacy button endpoint