Evidence-led field guide
Troubleshoot WhatsApp connection and messaging
Diagnose activation, authorization, number verification, profile review, templates, payment, webhook delivery, permissions, and tenant-routing issues safely.
Start with the named connection-health state and the approximate time of failure. Do not repeatedly reconnect, re-verify, migrate, or resend until the failing layer is understood. Never paste access tokens, passwords, verification codes, or customer message content into tickets.
Connect WhatsApp is missing
Possible causes include incomplete Tech Provider approval, a tenant module that has not been activated, or a user without connection-management permission. Ask the tenant owner to confirm the approved rollout and role. Do not grant broad administration merely to make a button appear.
Meta authorization does not open or complete
Allow popups for Balaawi, refresh an expired session, use a current supported browser, and confirm that privacy or network controls are not blocking the Meta window. Verify that the correct Meta business portfolio is selected. If authorization was revoked, an approved administrator must reconnect.
The number or display name is blocked
Confirm international number format, control of SMS or voice verification, current registration, provider ownership, and retry limits. For a pending or rejected display name, align the name and profile with the legal or publicly recognized business identity and follow the action shown by Meta.
Outbound messages fail
Review the exact status for payment readiness, authorization, recipient validity, consent, service-window state, template approval and variables, quality restrictions, role permission, and temporary provider errors. Correct the named requirement before retrying. Never use repeated sends as a health check.
Incoming messages are missing
Confirm the masked connected number, tenant status, authorization, webhook health, event subscription, and the time range. A platform operator should use connection metadata and safe event identifiers to diagnose routing while preserving tenant boundaries and customer privacy.
Safe support package
Provide the tenant name or approved identifier, masked phone number, safe error code, approximate time and timezone, browser version for authorization issues, expected action, observed result, and whether the issue affects all authorized users. Exclude secrets, full customer numbers, message bodies, and unnecessary personal data.
Questions teams ask next
What does Action required mean?
A connection-health check has identified a condition that needs an administrator, such as authorization, payment, registration, profile, template, webhook, or permission state.
Why can one employee not send?
Check their send permission, conversation assignment, consent state, service window, template eligibility, and tenant activation. Do not grant connection management just to enable sending.
Should I keep retrying verification?
No. Repeated attempts can increase disruption or rate limits. Confirm ownership, format, current registration, and the supported migration path first.
What may I send to support?
Send masked identifiers, safe error codes, timestamps, and observed behavior. Do not send passwords, access tokens, verification codes, customer message content, or unnecessary personal data.
Source register
References used to bound this guide. External sources open in a new tab.
- Embedded SignupMeta for Developers
- Set up Webhooks for WhatsApp Business AccountsMeta for Developers
- WhatsApp message templatesMeta for Developers
- WhatsApp Business Platform pricingMeta for Developers
- Balaawi WhatsApp production-readiness recordBalaawi SystemsInternal record
Evidence standard: Source-governed educational record
Plan one bounded review