OpenWa Desktop Guide

OpenWa sends WhatsApp messages from a linked personal number (WhatsApp Web), not the official Business Cloud API. Campaigns are paced automatically so the account is less likely to get restricted.

Campaigns send one recipient at a time. You do not set an interval in the campaign form — pacing is built in.

Built-in delay

• Between messages: random 5–15 seconds
• After about 18–25 sends: short rest (3–8 minutes)
• After about 120 sends: longer rest (20–40 minutes)
• Quiet hours: campaigns only send 09:00–21:00 local time; they pause overnight and continue the next morning

Daily caps apply mainly to new chats (people you have not messaged before). People who already have a chat with you use a larger budget and are sent first.

If WhatsApp reports its own new-chat quota, that is the hard ceiling. Otherwise OpenWa uses your volume tier (default Balanced). Change the tier under Send safety on Overview or WhatsApp QR.

Other tiers

• Safe: 80 → 150 → 250 → 400 → 600 / day
• Fast: 500 → 800 → 1,000 / day (higher risk on a fresh number)

An established (mature) number — many existing chats and older history — starts near the top of the ladder on day one. Fresh numbers warm up gradually.

Unused budget is not banked. If the app is closed all day, that day’s quota does not carry over. Each day starts fresh.

Before you queue a campaign, the create screen shows a safety preview: existing vs new chats and an estimated finish date (for example, 800 all-new chats on Balanced / fresh ≈ 3 days).

Urgent campaigns can borrow from tomorrow’s budget at most once every 7 days. They never bypass WhatsApp’s own quota, a CAPPED status, or a reachout lock.

Campaign progress is stored in the database. Closing the app mid-campaign does not lose remaining recipients.

• Closed less than ~12 hours: on next launch the campaign auto-resumes. Overview shows a short notice.
• Idle more than ~12 hours: the campaign is Paused and waits for confirmation so an old list never blasts unexpectedly. Use Resume on Overview or the campaign detail page.

You can also Pause, Resume, or Cancel manually. Pause keeps remaining jobs; Cancel marks them failed.

Crash safety: closing the app does not burn retry attempts on unsent recipients. If a send may have completed during a crash, OpenWa marks it sent (unverified) instead of messaging the same person twice.

You receive a ready-to-run installer. Configuration is baked into the build — you do not install Node, create a .env, or place extra config files beside the app.

Windows

• Setup installer — Run OpenWa-Setup-*.exe, choose an install folder, then finish. OpenWa adds Desktop and Start Menu shortcuts.
• Portable — Run OpenWa-Portable.exe with no install step. Session and campaign media still live under the app data directory, not next to the EXE.

macOS

• Download the DMG for your chip: arm64 (Apple Silicon) or x64 (Intel) — for example OpenWa-*-arm64.dmg.
• Open the DMG and drag OpenWa.app into Applications (or launch from Downloads).
• If Gatekeeper blocks an unsigned internal build: Right-click → Open → Open, or use System Settings → Privacy & Security → Open Anyway.

Need an installer for your team? Contact us for packaging and access.

Launch OpenWa. A native window opens on the admin dashboard — no CMD window and no need to open a browser yourself.

1. Sign in with the account your admin provided.
2. You’ll land on Overview — message stats, campaign status, and WhatsApp connection health.
3. Use the sidebar to reach WhatsApp QR, Questionnaires, Campaigns, Users, API Keys, API Connections, and API Docs (based on your permissions).

Superadmins can create brands and invite users with module-level grants so each teammate only sees what they need.

Everything else depends on a linked WhatsApp session. Connect from inside the app:

1. Open WhatsApp QR in the sidebar (Connection).
2. On your phone: WhatsApp → Linked devices → Link a device.
3. Scan the QR shown in OpenWa.
4. When the status shows Connected, inbound messages can drive your customer-care flows and outbound campaigns can send.

You can disconnect from the same screen when you need to rotate a device or stop the session. Session data stays under the app’s data directory on your machine.

Under Contacts, OpenWa syncs recent chats and saved contacts after you link WhatsApp (scan QR).

• Existing chat — safer; does not spend new-chat quota
• New chat — uses the daily new-chat budget

On campaign create, use Pick from WhatsApp contacts or paste numbers. Prefer existing-chat recipients when you can.

Questionnaires are your customer-care and support automation on WhatsApp — keyword-triggered chats that ask questions, branch on answers, show statements, and optionally call your APIs mid-flow.

• Open Questionnaires, create or edit a flow, then use Build, WhatsApp Preview, and Flow Diagram tabs.
• Set comma-separated trigger keyphrases (for example hi, hello, support, help). Matching is case-insensitive with word boundaries.
• Add steps: text, number, single select, multi select, statements, and API call nodes with success/failure paths.
• Attach images where helpful, validate email/number answers, and set completion or retry copy.
• Save, then Deploy. Only one questionnaire is active per brand at a time — deploy switches the live flow.

Once WhatsApp is connected and a flow is deployed, a customer who texts a trigger phrase enters the conversation automatically — that’s your always-on customer care lane.

Use Campaigns when you need the same announcement, offer, or brochure to many numbers.

• Paste a phone column from Excel or Google Sheets (lines, commas, or tabs). Set a default country code for local numbers (e.g. 91).
• Compose text and/or attach JPEG, PNG, or WebP. Or upload an HTML newsletter — OpenWa renders it to a PNG brochure (WhatsApp does not render HTML).
• Send now, or schedule a start time in your local timezone.
• Watch delivery progress, cancel in-flight jobs, and retry failed recipients from the campaign detail view.

Sends are paced to reduce rate limiting — see Campaigns and Send Safety and Daily Limits. Only message people who expect to hear from you.

• Campaign detail → Export Excel — summary, daily breakdown, full recipient list
• Reports page — brand-wide daily export for a date range, including safety stats (quota, capping, pauses)

Call OpenWa from your own backend, script, or third-party tool with a brand API key. Create keys under API Keys in the dashboard. The same reference also lives under API Docs inside the app.

Prerequisite — WhatsApp must be connected (scan QR) before POST /messages/send will succeed.

Create a Key

1. Open API Keys in the sidebar.
2. Create a new key for your brand.
3. Copy the secret immediately — keys look like owk_… and are shown once. Store them like passwords.

Base URL

Paths are relative to your OpenWa worker origin. Local default:

http://localhost:4100

Authentication

Pass the key on every authenticated request with either header:

X-API-Key: owk_your_secret_key_here

# or
Authorization: Bearer owk_your_secret_key_here

• Only active keys are accepted
• The key must belong to this worker’s brand
• Successful calls update the key’s lastUsedAt timestamp

Send a Message

POST /messages/send — send WhatsApp text from the connected account.

Body: to (international digits with country code) and text (message body).

curl -X POST http://localhost:4100/messages/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: owk_your_secret_key_here" \
  -d '{"to":"919876543210","text":"Hello from OpenWa"}'

Example success response:

{
  "ok": true,
  "id": "message-id",
  "status": "sent",
  "mode": "baileys",
  "to": "919876543210",
  "text": "Hello from OpenWa"
}

Simulate Inbound (Test Flows)

POST /messages/inbound — pretend a customer messaged you. Runs the active questionnaire and returns bot replies (useful for CI and custom UIs).

curl -X POST http://localhost:4100/messages/inbound \
  -H "Content-Type: application/json" \
  -H "X-API-Key: owk_your_secret_key_here" \
  -d '{"from":"919876543210","text":"hi"}'

Body fields: from (customer phone) and text (inbound message; can be empty).

Health Check

GET /health — public status (no API key). Confirms the worker is up and whether WhatsApp is connected.

curl http://localhost:4100/health

JavaScript Example

const res = await fetch("http://localhost:4100/messages/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.OPENWA_API_KEY,
  },
  body: JSON.stringify({
    to: "919876543210",
    text: "Hello from OpenWa",
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error || "Send failed");
console.log(data);

Python Example

import os
import requests

res = requests.post(
    "http://localhost:4100/messages/send",
    headers={"X-API-Key": os.environ["OPENWA_API_KEY"]},
    json={"to": "919876543210", "text": "Hello from OpenWa"},
    timeout=30,
)
res.raise_for_status()
print(res.json())

Common Errors

• 400 — missing or invalid body fields
• 401 — missing or invalid API key
• 403 — key not valid for this worker brand
• 503 — WhatsApp not connected or send failed

POST /messages/send also goes through the safety engine (looser delay than campaigns).

• Users & permissions — Invite teammates and grant modules (Questionnaires, Campaigns, WhatsApp QR, API Keys, and more).
• API Connections — Save HTTP endpoints your questionnaire flows can call mid-chat (Bearer, API key header, Basic, or none), with {{placeholders}} filled from answers. Separate from brand API keys above.
• Overview — Track message volume and campaign breakdown without leaving the desktop worker.

Conversation state for active chats lives in memory on the worker. Analytics keeps per-brand message counts for operations — not a warehouse of every customer reply. Campaign media is stored under the app data directory on your machine. Keep the workstation secured like any production host.