WhatsApp Send API

Integration docs for external platforms sending messages through this WhatsApp app.

This is unofficial WhatsApp automation, not Meta's Cloud API. The account this app is linked to can be banned by WhatsApp if it's used to send high volumes of unsolicited or identical messages quickly. This endpoint sends individual 1:1 messages on request — it is not a bulk/broadcast channel. If your platform needs to notify many users, space out your own calls to this endpoint (a few seconds apart, not machine-gunned in a loop) and only message users who expect to hear from you.

Getting an API key

Ask the admin of this WhatsApp app to generate one for you from the API Keys tab in the admin dashboard. Keys are shown in full only once, at creation time — if it's lost, the admin will need to revoke it and generate a new one. Treat it like a password: keep it on your server, never in client-side/browser code.

Base URL

https://YOUR-DEPLOYMENT-DOMAIN

Authentication

Send your API key as a bearer token on every request:

Authorization: Bearer wak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Send a message

Method	`POST`
Path	`/api/v1/messages/send`
Content-Type	`application/json`

Request body

{
  "to": "15551234567",
  "body": "Your order has shipped!"
}

to — recipient phone number, digits only, with country code and no leading + or spaces (e.g. 15551234567 for a US number, 447911123456 for a UK number).
body — the plain-text message to send.

Example (curl)

curl -X POST https://YOUR-DEPLOYMENT-DOMAIN/api/v1/messages/send \
  -H "Authorization: Bearer wak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "15551234567", "body": "Your order has shipped!"}'

Success response — 201 Created

{
  "id": 42,
  "to": "15551234567",
  "status": "sent",
  "wa_message_id": "true_15551234567@c.us_3EB0...",
  "created_at": "2026-07-27 15:03:11"
}

Errors

Status	Meaning
`400`	Missing/invalid `to` or `body`
`401`	Missing, invalid, or revoked API key
`422`	`to` is not a WhatsApp-registered number
`503`	The WhatsApp session isn't connected right now (e.g. needs re-linking)
`502`	An unexpected error occurred while sending; safe to retry

All error responses are shaped as { "error": "human-readable message" }.

Send to multiple recipients

Method	`POST`
Path	`/api/v1/messages/send-bulk`
Content-Type	`application/json`

This still sends one-at-a-time under the hood, with the same randomized delay between each recipient used everywhere else in this app — it does not send in parallel or instantly. That pacing exists to look like a human sending messages one by one rather than a bot blasting a list, which is what triggers WhatsApp's abuse detection. A batch of a few hundred numbers can take a while to fully send; poll the broadcast status (below) rather than expecting it to finish inside the request.

Request body

{
  "name": "July promo",
  "recipients": ["15551234567", "447911123456", "919812345678"],
  "body": "20% off this week only!"
}

name — optional label for this send (defaults to an auto-generated one identifying your API key).
recipients — non-empty array of phone numbers, same format as to above. Invalid entries are skipped, not fatal — see invalidRecipients in the response.
body — the message every recipient receives.

Success response — 201 Created

{
  "broadcast": {
    "id": 7,
    "name": "July promo",
    "message_body": "20% off this week only!",
    "status": "running",
    "created_at": "2026-07-27 16:00:00",
    "started_at": "2026-07-27 16:00:00",
    "completed_at": null
  },
  "progress": { "total": 3, "sent": 0, "failed": 0, "pending": 3 },
  "recipientCount": 3,
  "invalidRecipients": []
}

Sending has already started by the time you get this response. Poll broadcast.id to track progress (admin-only, requires the dashboard/admin token — there is currently no API-key-scoped status-polling endpoint).

Bulk-send errors

Status	Meaning
`400`	Missing `body`, empty/missing `recipients`, or every entry in it was invalid
`401`	Missing, invalid, or revoked API key
`503`	The WhatsApp session isn't connected right now

Scope of this key

API keys can only call the send-message endpoint above. They cannot read the inbox, manage contacts or lists, or trigger broadcasts — those remain admin-only actions inside the dashboard.