WhatsApp Business, without the sharp edges.
Every gotcha we have hit ourselves, or watched customers hit, documented so you can side-step it. Meta's Cloud API has some genuinely surprising behaviours; this is the field guide.
Managing a WhatsApp Business number
What actually happens when I click Deregister on a number?
We call Meta's POST /deregister endpoint. That fully removes the phone from the WhatsApp Cloud API. Meta's status for the phone flips toDISCONNECTED.
Re-adding via Embedded Signup does not undo this. The re-add authorises the app with the WABA again and stores a fresh token, but the phone stays disconnected until you explicitly re-register it with a 6-digit PIN.
Rule of thumb: never use Deregister as a troubleshooting step. If a number is misbehaving, contact support first — deregister is meant for permanently retiring a number.
I deregistered by mistake. How do I recover?
You need two things: SMS access to the number, and about 5 minutes.
- In WhatsApp Manager, turn off Two-Step Verification for the phone (this may show "Account does not exist in Cloud API" when trying to reset the PIN — that's expected because the Cloud API account is gone; turning off 2FA still works).
- Contact support so we can run the
request_codeAPI. Meta will SMS a 6-digit code to your number. - Forward the code to us. We verify it and re-register the phone with a new PIN of your choice.
- Save the new PIN. WapiSnap does not store your Cloud API PIN — you own it.
I tried a few PINs and now Meta says 'phone number re-verification needed'.
After three wrong PIN attempts Meta locks the register endpoint until you re-verify the phone via SMS or voice code. The good news is the recovery is exactly the same as the previous question — turn off 2FA in WhatsApp Manager, ask us to trigger the SMS, forward the code, we finish it.
Do not repeatedly retry the register call. Every failed attempt extends the lockout window.
Non-admin users see 'Feature Unavailable' when connecting a WhatsApp number.
Full Meta message: "Facebook Login is currently unavailable for this app, since we are updating additional details for this app." It has nothing to do with app review status — the login configuration is missing the public_profile permission.
Admins and developers get all app permissions implicitly, which is why the workspace owner never sees this and only invited teammates do. Fix on the Meta App side: open the login configuration and add public_profile alongside the WhatsApp scopes. Takes effect immediately, no app review re-submission needed.
Why messages fail (and what to do about it)
Broadcast returns error 131049. What is it?
Marketing frequency cap. Meta limits how many marketing messages a single recipient can receive across ALL senders in roughly a 7-day window. When your broadcast hits a recipient who is already saturated, Meta rejects with 131049. It's not a WapiSnap issue and it's not something you did wrong on that specific send — the customer just already got marketing from someone else recently.
What WapiSnap does about it: Smart Retry detects 131049 specifically and uses a long backoff ladder (7d / 8d / 9d) instead of the standard hours-scale retries. That way we don't waste attempts inside Meta's cooldown.
I keep hitting 131026 on the same contacts.
131026 = "recipient not on WhatsApp". Some contact lists have chronically-undeliverable numbers (landlines, wrong digits, users who left WhatsApp). Retrying doesn't help.
Recommended: after 2 consecutive 131026 failures for a contact, tag them do-not-send and exclude them from future broadcasts. Distinct from the dnd tag which is a customer-initiated opt-out.
What is the 24-hour customer service window?
Meta's core policy: you can send free-form (non-template) messages to a customer only within 24 hours of their last inbound message to you. Outside that window, all outbound messages MUST be from a pre-approved template.
What WapiSnap does about it: the inbox composer just works — if the window is open, you type and send; if it's closed, the template picker is highlighted. The flow engine's sendTemplate node is the correct choice for outreach outside the window; sendMessage is for reactive replies.
Why does a flow's sendTemplate work but the inbox template picker doesn't?
Two common causes: the template is not APPROVED at Meta (check Templates page → status), or the workspace is on a messaging-tier limit (Meta caps new WABAs to ~250 unique recipients/24h until quality metrics build up). Templates page shows both.
For Instagram conversations, templates are simply not a thing — Meta's Instagram Messaging API has no equivalent to template messages. The inbox hides the template button on IG threads for this reason.
Flows, DND, and human handoff
How does the DND tag work?
dnd is a reserved system tag. Adding it to a contact blocks:
- All flow
sendMessage/sendInteractive/sendTemplatenodes - Broadcast inclusion (both tag-based and CSV imports)
- Smart Retry resends
But it does NOT block direct human replies from the inbox composer — a customer opting out of automation still deserves a human response if they message you. The tag is workspace-scoped; the same customer with the tag in workspace A has no effect on workspace B.
An agent replied and the bot went silent. Why?
By design. When any human sends a TEXT, MEDIA, or INTERACTIVE message from the inbox composer, WapiSnap flips the conversation's humanHandoff flag to true. Any active flow stops on the next tick. This prevents the classic footgun where a bot enthusiastically interrupts a human conversation.
Exception: TEMPLATE sends do NOT trip handoff. Templates are proactive outreach (e.g., the welcome card that asks a question to drive the bot funnel); the bot is supposed to respond to the customer's reply to the template.
To re-enable automation for a conversation after handoff, toggle the "Human takeover" switch off in the conversation header.
My automation doesn't fire on Instagram DMs.
By design, again. Every automation trigger has a channel filter that defaults to WhatsApp. This prevents pre-existing WA automations from unexpectedly firing on IG conversations after you connect an Instagram account.
Open the automation, click the trigger node, and set channel to "Instagram" or "Both". Also note that some node types are WhatsApp-only — sendTemplate, sendInteractive, sendWaFlow skip cleanly with an error on IG conversations because Meta's IG API doesn't support those constructs.
Webhooks, tokens, and health checks
Inbound messages stopped arriving. Where do I look?
Six things, in order:
- Numbers page — is the status ACTIVE (not DRAFT or ERROR)?
- Meta App Dashboard → WhatsApp Business Account → confirm the callback URL matches the one shown on your Numbers page.
- Meta App Dashboard → the subscribed fields include
messages. - WhatsApp Manager → Phone Number → status should be CONNECTED.
- If deregistration ever happened for this number, the recovery flow above (SMS re-verify) is required.
- Still stuck? Send us the phone number ID — we can query Meta directly and tell you exactly which step is broken.
What token do you store, and how safe is it?
We store the WhatsApp Cloud API access token you (or Meta's Embedded Signup flow) authorises. It's encrypted at rest with AES-256-GCM using a workspace-agnostic infra key, and only ever decrypted in-memory on outbound calls to Meta. It is never logged, never returned in API responses, and never written to any secondary system.
We show only the last 4 characters of the token in the UI so you can identify a rotation. The full value only exists on the API host's memory during a send.
Can I have the same number in two WapiSnap workspaces?
No — one number belongs to one workspace at a time. If you need to move it, deregister (following the caveats above) then re-onboard it in the other workspace. Contact data, tags, and conversations do NOT transfer; they stay with the original workspace.
Why do some of my messages show status FAILED with no error message?
Rare but real. It means Meta returned a 2xx response but never sent a delivery/read status callback within the retention window. Usually the recipient blocked your business number shortly after receiving the send — Meta stops reporting statuses for blocked conversations.
Not indicative of a WapiSnap issue. If it happens broadly (say, >5% of a broadcast), open a support ticket with the affected message IDs and we can trace via Meta's webhook debugger.
Not covered here?
Meta's Cloud API surface is deeper than any FAQ. If your situation isn't listed, drop us a note — we'll either help fix it and add the answer here, or point you at the Meta doc that covers it.
Your WhatsApp. Your AI. Your rules.
Join businesses automating WhatsApp without vendor lock-in.