WhatsApp onboarding
Link a WhatsApp or WhatsApp Business app account to a workspace with a QR code or a pairing code.
Each workspace is one OpenWA session, which is one linked WhatsApp account. The owner links it the same way as WhatsApp Web: by scanning a QR code or entering a pairing code under Linked devices. There is no Meta app, business verification or registration PIN.
Unofficial: the number can be restricted or banned
OpenWA is not affiliated with Meta. Automating a WhatsApp account can violate WhatsApp's terms and get the number restricted or banned. Tell the business owner this before they link anything. Recommend a dedicated number, low volume, and opt-in customers only. See Ban-risk practices.
For operators (one-time platform setup)
Run the gateway
Start OpenWA with docker compose up -d openwa and put its admin key in OPENWA_API_KEY. See Getting started.
Webhook secret and URL
Set OPENWA_WEBHOOK_SECRET (openssl rand -hex 32) and, if the gateway cannot reach PUBLIC_URL/webhooks/openwa, OPENWA_WEBHOOK_URL. The engine registers the webhook for each session when the workspace connects, so there is nothing to configure in a dashboard.
Capacity
Each linked account runs a headless Chromium (about 300 to 500 MB of RAM). Raise OPENWA_MEM_LIMIT before onboarding more workspaces.
For customers (what the business owner does)
The page lives at Connect WhatsApp in the admin app and requires the workspace owner or admin role.
Prepare
Have the phone with the WhatsApp or WhatsApp Business app logged in to the number the assistant should use. A dedicated number is strongly recommended. Linking keeps the phone working normally: staff can still read and reply from it.
Start the connection
Open Connect WhatsApp and start the connection. The engine creates the workspace's session, registers its webhook and starts it. A QR code appears when the session reaches qr_ready.
Link the device
On the phone open WhatsApp, Settings, Linked devices, Link a device and scan the QR code. The code rotates, so the page keeps refreshing it.
To link without scanning (for example when you are on the phone itself), choose Link with phone number instead in WhatsApp, enter the number in the admin app, and type the pairing code it shows.
Wait for ready
The status moves through qr_ready, authenticating and ready. When it reports ready the page shows the linked phone number and the connection becomes active.
Publish the assistant and upload knowledge
A connected number only answers once its workspace has a published assistant. Open Assistant to review persona, languages, AI disclosure, and handoff messages, then Knowledge to upload .txt or .md files. See Knowledge and answers.
What happens on the server
POST /admin/session/connect: creates the OpenWA session (named from the workspace id) if none exists, insertschannel_connectionand achannel_routerow so inbound webhooks map to the workspace, writes achannel.createaudit event, ensures the webhook is registered, and starts the session.POST /admin/session/qr: syncs the status and returns the QR code as a PNG data URL, or the phone number onceready.POST /admin/session/pairing-coderequests a code for a phone number instead.- Webhook events (
session.status,session.authenticated) flip the connection toactiveand record the phone number and push name.
After linking
- Relinking. If the device is unlinked from the phone, or the session is logged out, the connection becomes
disconnected, inbound events are ignored and queued replies are discarded as "channel inactive". Run the connection flow again and scan a new QR code. See Operations. - Disconnecting on purpose.
POST /admin/session/logoutunlinks the device from the phone and marks the connectiondisconnected. - Groups. Add the linked number to a WhatsApp group the normal way, or create one from the Groups page, then enable group answers on the assistant. See Voice notes, groups and calling.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| No QR code appears | The gateway is down or still starting (check docker compose ps and the health check), or OPENWA_URL or OPENWA_API_KEY is wrong (the admin shows a 502 with the gateway status). |
| QR scan fails or expires | The code rotated. Wait for the next one, or use a pairing code. |
Stuck in authenticating or failed | Run the connection flow again (it restarts a session that is not ready). If it repeats, check the gateway logs and memory limit. |
Session ready but no events arrive | The gateway cannot reach the engine webhook. Check OPENWA_WEBHOOK_URL, SSRF_ALLOWED_HOSTS (local dev) and the signing secret. A bad signature returns 401. |
| Connected but no replies | No published assistant, connection not active, conversation in human mode, contact blocked, or a group not addressing the assistant. |
Connection flips to disconnected | The device was unlinked on the phone, or WhatsApp logged it out or restricted it. Relink, and review Ban-risk practices. |
Getting started
Prerequisites, the OpenWA gateway, environment variables, Neon setup, local development, linking a phone, and deploy.
Knowledge and answers
Ingestion and chunking, full-text retrieval, citation enforcement, handoff rules, prompt caching, model and effort configuration, cost, and refusal fallbacks.