Skip to content
S SiPesan Docs
ID EN

WhatsApp Web (QR) Broadcast

WhatsApp Web (QR) broadcast lets you send one message to many numbers over the WhatsApp Web channel — the channel you connect by scanning a QR code (like WhatsApp Web in a browser), without the official WhatsApp Business API. Broadcasts are triggered via the API, sent gradually with automatic delays to stay safe from blocking, and delivered/read status is tracked per recipient. The feature is free (no balance is charged) and, in this first version, text-only.

When to use this

Use WhatsApp Web broadcast when you want to reach many customers but don't use the official WhatsApp Business API (WABA). Unlike WABA broadcast, which uses paid HSM templates, WhatsApp Web broadcast sends plain text messages from the number you scanned. Because it uses an unofficial path, sending is deliberately slow with daily caps to keep your number safe.

Prerequisites

Before sending a broadcast, make sure:

  • The WhatsApp Web channel is Connected. Create and scan the QR in the business panel under the WhatsApp Web menu. The channel status must be Connected. If it disconnects, the broadcast is paused automatically until it reconnects.
  • An API key exists. Open the business panel → Developers → API Access to get your Public Key (pk_…) and Secret Key (sk_…).
  • The Channel ID is ready. Copy the WhatsApp Web channel's Channel ID from the WhatsApp Web menu — you'll use it when calling the API.

How paced sending works (anti-block)

WhatsApp Web broadcast is not sent all at once. The system sends one message per random delay (a few seconds between messages), with several safeguards:

  • Hourly and daily caps — limit volume so it doesn't look like spam.
  • Warmup (optional) — for new numbers, the daily quota is raised gradually day by day.
  • Business hours (optional) — sending only runs within a configured time window.

As a result, a large list trickles out over time — not within seconds. The broadcast status moves from sending to completed once all recipients are processed. These safeguards are configured by the admin per channel.

Controlling the send rate (throttling)

There are two levels of throttling control:

1. What you can set yourself — the per-channel daily limit. Go to the business panel → WhatsApp Web menu → edit the channel → the Daily Message Limit field. This caps how many messages that channel sends per day. The effective cap = the smaller of your channel limit and the platform safety ceiling.

2. What the SIPESAN team manages (platform level). The knobs below are global and set in the server configuration (.env), not per channel — contact your SIPESAN admin to change them. Defaults:

  • Delay between messages — 6–20 seconds, random (WAWEB_BCAST_MIN_DELAY / WAWEB_BCAST_MAX_DELAY).
  • Hourly cap — 120 messages (WAWEB_BCAST_HOURLY_CAP).
  • Hard daily ceiling / safety — 1000 messages (WAWEB_BCAST_HARD_DAILY).
  • New-number warmup — disabled by default; when enabled, day 1–5 quotas = 20 / 40 / 80 / 120 / 160 messages (WAWEB_BCAST_WARMUP_ENABLED).
  • Business hours — disabled (sends 24h) by default (WAWEB_BCAST_HOURS_ENABLED, WAWEB_BCAST_HOURS_START, WAWEB_BCAST_HOURS_END).
  • Disconnect timeout — 24 hours (WAWEB_BCAST_DISCONNECT_TIMEOUT).
  • Max recipients per request — 5000 (WAWEB_BCAST_MAX_RECIPIENTS).

For new, un-warmed numbers, lower the channel's daily limit and ask your admin to enable warmup so the number isn't banned quickly.

Sending a broadcast

Broadcasts are sent via the REST API. Full technical details (auth headers, request/response format, error codes) are in the API, Testing & Error Codes topic. In short, you call POST /api/v1/business/waweb/broadcasts with:

  • channel_id — the Connected WhatsApp Web Channel ID.
  • message — the text body (max 4096 characters).
  • recipients — the list of destination numbers (free format; auto-normalised and de-duplicated).
  • name (optional) — a broadcast name for easier tracking.

You receive a broadcast id you can use to check status via GET /api/v1/business/waweb/broadcasts/{id}.

Message variation (spintax)

Sending identical text to many numbers raises the blocking risk. Use spintax to add variation: write several word choices in curly braces separated by a pipe, and the system picks one at random per message.

Example: {Hi|Hello|Good afternoon}, we have a new {promo|offer}! is sent as one of the combinations, differing per recipient. Spintax can be nested.

Delivered & read status

Each recipient is tracked through statuses: pending → sent → delivered → read, or undelivered on failure. You can monitor two ways:

  • Dashboard — open the broadcast under the Broadcasts menu to see the summary (sent, delivered, read, failed) and per-recipient status. The cost column is hidden because WhatsApp Web broadcast is free.
  • Webhook — if you configure a webhook URL (business panel → Developers), SIPESAN pushes a real-time notification on every delivered, read, and undelivered status (with its reason). Payload details and signature verification are in the Webhook topic.

Possible failure reasons (reason): account_banned (the number was banned by WhatsApp), channel_disconnected_timeout (the channel stayed disconnected too long), opted_out (the customer unsubscribed), and channel_missing (channel not found).

Unsubscribe (opt-out)

A customer who replies STOP or BERHENTI (also UNSUBSCRIBE) is automatically recorded as opted out. That number is skipped on future broadcasts and recorded as undelivered with reason opted_out. This helps you respect customer choice and protect your number's reputation.

First-version limits

  • Text only — images and media are not supported yet (they're rejected).
  • Free — no cost, no balance deduction.
  • Unofficial path — WhatsApp Web is not Meta's official API. A number can be restricted if you send too aggressively; that's why sending is paced and opt-out exists. Still send only to relevant customers at a reasonable frequency.
  • Maximum 5000 numbers per request.