Trigger WhatsApp Messages from Your App (HTTP API)

Typing messages one by one in a panel is fine for small lists. But the moment you want an order confirmation, an appointment reminder or a form reply to go out automatically, you need a channel that does not wait for a human. That is exactly what an HTTP API gives you: your app sends the server a small JSON request, and the message goes out to WhatsApp at a safe pace. This article walks through the HTTP API integration for this QR-based system (not the official Business API): the endpoint shape, the auth secret, an example curl/JSON payload and the queue model behind it.

1. Why you need an HTTP API

A panel UI is great for manual sends, but it breaks down in three situations:

• Event-driven messages: When an order is placed, a form is submitted or a payment clears, a notification should fire immediately. You cannot wait for someone to open a panel and type.
• Integration with existing systems: Your e-commerce stack, CRM or accounting tool already knows about these events; you just want to bridge them to WhatsApp.
• Volume and consistency: Hand-writing hundreds of personalized notices (each with a name and order number) is impossible; they must be generated from a template plus data.

An HTTP API turns your panel into an automation endpoint. This is the most programmatic form of sending automated WhatsApp messages: the trigger is no longer a person, it is your code.

2. Where the request goes: the flow

The system's golden rule: the server never sends; only the worker sends. Your HTTP request starts that chain but does not fire the send directly:

3. Endpoint shape and authentication

The API surface is deliberately small. Picture a single send endpoint (the exact path may vary by your version; the shape here is illustrative):

Authentication rests on a single shared secret: WA_CONTROL_SECRET. You generate it at setup with openssl rand -hex 32, put it in .env, and send it only from your server-side code. The server queues nothing until the secret in the incoming header matches the expected value.

4. Example request: curl and JSON payload

The simplest text send looks like this with curl:

curl -X POST https://your-server.example.com/api/messages \
  -H "Content-Type: application/json" \
  -H "X-Control-Secret: $WA_CONTROL_SECRET" \
  -d '{
    "to": "905551112233",
    "message": "Hi Jane, order #1043 is being prepared. Reply STOP to opt out of notifications.",
    "sendAt": null,
    "priority": "high"
  }'

A successful response reports that the message was queued, not that it was sent:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "queued",
  "jobId": "wa_9f3c1a7b",
  "queuedAt": "2026-07-31T10:14:22+03:00"
}

A few notes on the fields:

• to: Give the number with a country code, without a leading + or 0 (e.g. 905551112233). The system normalizes it to a chatId; the recipient does not need to save you first. Detail: messaging without saving contacts.
• message: Plain text; you fill in personalization (name, order number) as you build the payload.
• sendAt: Pass an ISO 8601 time and the job is deferred via BullMQ delay; leave it empty and it goes out in the next valid window. See scheduling WhatsApp messages.
• priority: Sets this job's weight in the round-robin ordering described below.

5. Round-robin priority: one sender, many sources

Because the worker is a single sender at any moment, jobs from different sources (a bulk campaign plus a one-off order notice) share the same bottleneck. The system applies round-robin priority here: high-priority one-off notices (order confirmations, appointment reminders) are not stuck for hours behind a campaign of thousands; they are fairly interleaved between campaign jobs.

6. Use cases

6.1 E-commerce order and shipping

When an order status changes (confirmed, shipped, delivered), your backend fires a POST and the customer is informed instantly. Because this counts as a service notification, it is more flexible than marketing consent — still, review the details in order & shipping notifications.

6.2 Web forms and lead alerts

When a contact form is submitted, both your team and the user can get an automatic "we received your request" message. Your form backend hits the endpoint directly.

6.3 CRM and automation tools

A stage change in your CRM, or an automation flow in a tool like n8n or Zapier, can call this API from an HTTP node. That way you add a WhatsApp step through a visual flow without touching code.

For what all of this means on the infrastructure side, see the self-hosted messaging system; the worker/queue architecture around the API runs entirely on your own server.

Frequently asked questions