WhatsApp QR (unofficial)
Read this first
This channel links an existing WhatsApp account to WhatsMax as a companion device, using a protocol Meta does not support or endorse. The number can be banned. Use a number you can afford to lose, and prefer the official Cloud API channel wherever you can.
When to use it
The Cloud API is the right choice for almost everyone. The QR channel exists for one situation: a team already runs its business from a normal WhatsApp or WhatsApp Business app, on a number they cannot or will not migrate.
| Cloud API | WhatsApp QR | |
|---|---|---|
| Supported by Meta | Yes | No |
| Setup | Business verification | Scan a QR code |
| Templates | Required outside 24h | Not available |
| 24-hour window | Applies | Does not apply |
| Free-form messages | Only inside the window | Any time |
| Group chats | Not supported | Supported |
| Throughput | High | Deliberately throttled |
| Ban risk | None | Real |
Requirements
WHATSAPP_QR_ENABLED=truein.env- Redis (the gateway will not start without it)
- The
whatsmax-gatewayprocess, running as exactly one instance — see Production deployment - A phone that stays online; if the phone loses connectivity for long enough, WhatsApp unlinks the companion device
Linking a number
- Inbox → Channel Setup → WhatsApp QR → Link a number.
- Read the risk screen and tick the acknowledgement. This is recorded with your user and a timestamp.
- Choose how to link:
- Scan QR — on the phone: WhatsApp → Settings → Linked devices → Link a device. The code refreshes every 60 seconds and gives up after 5 codes.
- Pairing code — enter the number, then on the phone choose "Link with phone number instead" and type the 8-character code. Useful when there is no second screen to scan from.
- The card shows Connected once the socket opens.
Anti-ban pacing
Campaign sends through this channel are paced on purpose. Defaults:
| Setting | Default | Why |
|---|---|---|
| Delay between sends | 8–25s, randomized | Uniform timing is machine-obvious |
| Daily cap | 500 | Volume ceiling per number |
| Warmup | 30/day rising to the cap over 14 days | New devices sending in bulk are the clearest ban signal |
| Quiet hours | 22:00–08:00 local | Night-time bursts look automated |
| Typing simulation | On | Sends a "typing…" indicator first |
| Bulk verification | Blocked for the first 3 days | Existence checks are riskier than sending |
Agent replies, AI auto-replies and automations are not subject to the daily cap or quiet hours — a person typing in the inbox is not bulk traffic. They still serialize per number with a short random delay.
Troubleshooting
"Gateway offline" on the account card The whatsmax-gateway process is not running, or cannot reach Redis. Start it with node scripts/gateway and check its log. This is distinct from the number being offline.
Status is "Unlinked" The device was removed from the phone (WhatsApp → Linked devices), or WhatsApp invalidated the session. Link the number again.
Status is "Blocked by WhatsApp" WhatsApp rejected the account. Relinking will not help. Contact WhatsApp support about the number; do not keep retrying, which makes matters worse.
Status is "Error — connection replaced" Another process took over the session. Almost always a second gateway running somewhere. Confirm you have exactly one.
The QR expires before it is scanned Each code lasts about 60 seconds and the dialog issues 5 before stopping. Press Start over.
Messages arrive but the customer stops getting phone notifications That is what markOnlineOnConnect causes, and WhatsMax sets it to false precisely to avoid it. If you see this, check that you are not running a modified gateway.
Manual QA checklist
Some behaviour cannot be covered by automated tests: the WhatsApp handshake, whether WhatsApp accepts a given message shape on today's server build, real rate limits, and real ban behaviour. Run this checklist against a burner number before any release that touches this channel.
- [ ] Link by QR
- [ ] Link by pairing code
- [ ] Send a text message
- [ ] Send an image, a document and an audio file
- [ ] Receive each of: text, image, document, audio, sticker, location, contact
- [ ] Receive a reply/quote and a reaction
- [ ] Receive a group message (if groups are enabled)
- [ ] Confirm delivery and read receipts reach the inbox
- [ ] Put the phone in airplane mode; confirm the status reflects it
- [ ] Unlink from the phone; confirm the status becomes "Unlinked" and agents are notified
- [ ] Unlink from WhatsMax; confirm the device disappears from the phone
- [ ] Restart the gateway with a live session; confirm it reconnects
- [ ] Start a second gateway; confirm the first keeps the session and the second declines it