WhatsApp Troubleshooting

Most WhatsApp problems live on the Meta side — billing, registration, webhook configuration — and look like Brixi problems from where you sit. This page works through the common ones, starting with the classic: the number that refuses to show up when you try to link it.

Entry pointAutomation → Integrations → Social Media → WhatsApp

My Number Isn't Visible in the Meta Picker

You're in the linking flow, you've signed in to Meta, and the number you want simply isn't in the list. Work down this checklist — the first two cause the vast majority of cases:

Cause	What to do
No payment method / line of credit on the WABA	Meta won't list a number from a WhatsApp Business Account that has no way to pay for conversations. In Meta Business Manager → Billing, add a payment method or confirm the line of credit is active and shared with the WABA.
Billing not linked to the right WABA	A payment method can exist on the business but not be attached to this specific WhatsApp Business Account. Open the WABA's settings and confirm the payment account is assigned.
Number not registered to the WABA	The number must be added and verified inside the WhatsApp Business Account first (Business Settings → WhatsApp Accounts → the WABA → phone numbers).
Number still active on the WhatsApp / WhatsApp Business app	A number in use on the regular app can't join the Cloud API. Delete the account in the app (Settings → Account → Delete), wait a few minutes, then retry.
Business verification pending or rejected	Some capabilities are held back until Meta verifies the business. Check Business Manager → Security Centre for verification status.
You signed in with the wrong Meta account	The picker only shows assets your Meta user has a role on. Sign in with an admin of the business that owns the number.
Number already linked to another app or BSP	A number can serve only one Cloud API app at a time. Disconnect it from the other provider before linking it to Brixi.
Two-step verification PIN blocking registration	If the number had WhatsApp 2FA enabled, you'll need that PIN during registration — or wait out Meta's reset period.

Messages Not Arriving in Brixi

Problem	What to check
Inbound messages visible in Meta, absent in Brixi	The messages webhook field isn't subscribed in your Meta App, or the webhook handshake never completed — re-run Step 4 of the connect wizard.
Delivery/read ticks not updating	Subscribe to message_deliveries and message_reads webhook fields.
Inbound message created a new lead instead of matching the contact	The saved contact number is missing the country code — fix it and merge the duplicate.
No lead created for a new number	Lead generation is toggled off on the number's settings.

Sending Problems

Problem	What to check
Free-form reply won't send	The 24-hour customer service window has closed — send an approved template instead.
Template send rejected	The template isn't approved, was paused by Meta, or the variables don't match — check status in the Content Library.
Deliveries throttled or failing in bulk	Check the number's quality rating and messaging limits in Meta Business Manager — new numbers start with low daily conversation caps that grow with good quality.
Everything stopped working weeks after setup	Almost always an expired access token. Replace it with a permanent system user token and re-authenticate.

Agent and Sync Problems

Problem	What to check
AI agent not replying	Agent must be Active on the number card and its flow published — see Assign an AI Agent.
Chrome extension stopped syncing	See the Web Sync troubleshooting — usually an expired session or a disabled extension.

Still Stuck

If the Meta-side checks pass and the problem persists, see Getting Help. For WhatsApp issues, include the connected number's account name, your Meta App ID, the step or message that fails, and a timestamp — that's what support needs to trace a message through the webhook.

Related articlesFull Meta Cloud API Setup GuideLink a WhatsApp Business NumberDirect Linking with a System User