Troubleshooting

Symptom first, cause second.

Pairing and connection#

The QR code keeps changing#

Normal. WhatsApp rotates it every few seconds. Scan whichever code is on screen when your camera is ready.

Pairing fails immediately, repeatedly#

WhatsApp rate-limits device linking. After several fast failures PromotionBot puts the number into a 30-minute cooldown and shows you when it clears.

Wait it out and scan once. Retrying into a WhatsApp link-block extends the block — the cooldown is protecting you, and it deliberately survives an app restart so a deploy can't hand you a fresh retry button.

Stuck on "syncing history"#

WhatsApp is pushing your chat history to the new device. It usually takes under a minute. If it's clearly stuck:

Use Continue without history. The app offers it after a short wait, or immediately once it detects the sync has stalled. You keep the connection; your group list fills in as messages arrive in those groups. Nothing is lost. More on history sync.

The number keeps disconnecting#

In rough order of likelihood:

• The phone is off, offline, or WhatsApp was force-quit. The linked device needs the phone to be reachable.
• Someone unlinked it from WhatsApp → Linked devices.
• Another tool is using the same number. Two unofficial clients on one account fight over the session; one will keep losing.
• WhatsApp restricted the number. In that case all sending for your organisation is paused and the owner is emailed — see what happens then.

Groups#

A group isn't in my list#

• It only appears after history sync. If you skipped sync, the group appears once there's activity in it.
• The linked account must be a member. PromotionBot can't see, join, or message a group its account isn't in. Add the account from WhatsApp.
• It might be marked inactive. Check the inactive filter.

I can't select a group in Compose#

Two usual causes: the group belongs to a different number than the one selected in Compose, or it's inactive.

Compose is locked#

Compose needs at least one group tagged off the default general bucket. The lock screen says which setup step you're on and links to it.

Sends#

Groups were skipped#

The skip reason is shown per group, both in the delivery preview and in the send summary. There are four possibilities:

My new number won't send to all my groups#

If the number was linked in the last few days, Compose will say "This number is still building up" and show the allowance it has today plus when it next rises. That's the new-number ramp, not a fault and not a plan limit — see new numbers start small.

There is no override for it and no plan that lifts it. What to do instead: send to fewer groups now and schedule the rest — deferred sends go out on their own as the allowance grows. If you're mid-onboarding, linking the number a few days before your first big send avoids this entirely.

Note it follows the number, so if you re-linked a number you'd already been using, it keeps its existing age and this isn't what you're seeing — check Groups were skipped instead.

The send is taking minutes#

Working as intended. PromotionBot types like a person: a typing indicator, a pause scaled to message length, then a randomised gap before the next group. Forty groups takes several minutes. There is no fast mode — the pacing is the anti-ban feature.

I sent the same thing twice#

Ad-hoc sends carry no source, so no cooldown applies to them at all — only the daily cap does. Firing the same message twice manually will send it twice. Scheduled, campaign, and event sends are cooldown-protected.

Nothing sends at all#

• Subscription inactive? Sending stops (nothing is deleted) — see Plans & billing.
• Monthly message cap reached? Check usage in the billing section.
• Audience larger than 60 groups? The per-number ceiling is 60 messages an hour and 400 a day. Compose stops and offers Send anyway — I accept the risk (admins only); the safer choice is to split the audience or let a campaign spread it. Scheduled sends and campaigns aren't rejected — they're deferred until the ceiling allows them. See sending past the rate ceiling.
• Sending paused? A detected ban pauses everything org-wide and never auto-resumes; the emergency stop on the dashboard does the same thing manually. Both need a human to clear.
• Number disconnected? See above.

A send failed for some groups#

Reasons and groups are recorded on the Analytics page. Most common: the linked account was removed from the group, or WhatsApp rejected the media.

A cluster of failures in one send is different from one-offs — that's when the circuit breaker stops the rest of the fanout, and it's worth investigating before your next send.

I'm a member and my send didn't go out#

It became an approval request. An admin needs to approve it. Your button will read "Pending approval" until then.

Links and analytics#

Clicks aren't being counted#

• The link must be a full http(s):// URL in the message text. yourassociation.nl/gala without the scheme isn't rewritten.
• You need to have actually sent — clicks only exist for messages that went out with a rewritten link.
• Clicks come from real people opening links, so allow time. A message sent at 09:00 has most of its clicks by early evening.
• Check the message that was actually delivered — open the group in WhatsApp and look at the link that arrived. The delivery preview shows the resolved text before you send, but only a real send produces a tracking link.

Analytics is locked#

It unlocks after your first successful send. There's nothing to chart before that.

My click rate looks wrong#

Read the limits section. In particular: click figures are counted in groups, not people, while delivery and read rates are counted per recipient — so don't quote the two as if they share a denominator. Receipts also only exist for sends made after the feature was switched on, and a blank there means not measured, not zero. A high click rate on a tiny group isn't a trend either — the volume cue under each bar exists to keep you honest about that.

Monitor shows an upgrade prompt#

Monitor is on Team and Pro. Plans & billing.

Still stuck#

Email [email protected] with what you did, what you expected, and what happened. If it's a bug in the app, use the in-app bug-report button instead — it attaches the version and console context, which usually turns a two-day exchange into one reply.