Troubleshooting Guide

Problem

Meta blocks the number from connecting due to low activity, recent creation, or unclear trust signals.

Solution

Use the number actively on WhatsApp Business App for a few days, or register a fresh number. In some cases, delete and recreate the WhatsApp account.

Problem

The onboarding flow crashes or fails to complete properly.

Solution

Enable popups in your browser, use desktop instead of mobile, clear cache, and ensure all permissions are accepted during the flow.

Problem

WhatsApp Business App fails to scan or link during coexistence setup.

Solution

Retry with stable internet, restart the app, or generate a new QR code. If still failing, go to WhatsApp Business App > Account > Business Platform > Connect to a platform and use a manual code instead.

Problem

Meta rejects the business display name during setup.

Solution

Use your exact legal business name. Avoid marketing keywords, slogans, or generic terms. Resubmit with a clear, verifiable business name that matches your registration documents.

Problem

Business cannot proceed because verification is not available or stuck in review.

Solution

Ensure all business details are complete and consistent across Meta Business Suite. Double-check your business documents match the registered name and address. Wait for Meta to process, or contact support if stuck for more than 5 business days.

Problem

The account is not allowed to send messages due to billing eligibility issues, even if a payment method is added.

Solution

Make sure the card is set as the default payment method, not backup. Add your Tax ID under the payment method settings. If still blocked, raise a support ticket to Meta through your provider.

Problem

Card is added but not accepted or selectable for billing.

Solution

Remove and re-add the card. Ensure it is set as default and matches your business country. Try another card if needed. If still blocked, raise a support ticket to Meta through your provider.

Problem

Meta fails to process payment method addition due to internal errors.

Solution

Retry after a few hours, use a different browser or network, or try a different card. This is typically a temporary Meta-side issue.

Problem

Coexistence connection keeps dropping and reconnecting repeatedly.

Solution

Avoid linking multiple devices simultaneously. Reconnect once and wait for the connection to stabilize. If persistent, reconnect fully or consider switching to Cloud API for more stable connectivity.

Problem

WhatsApp temporarily restricts the business app after linking multiple devices.

Solution

Wait 24 hours and avoid connecting additional devices during this period. API messages will continue to work normally during the restriction.

Problem

WABA (WhatsApp Business Account) or phone number is no longer accessible or has been removed.

Solution

Check if your WABA is still attached to your business portfolio in Meta Business Suite. Reconnect or recreate the WABA if needed.

Problem

API stops working due to an invalid or expired access token.

Solution

Refresh your access token and ensure all required permissions are still granted in your Meta app settings.

Problem

API shows "sent" status but messages never reach customers and no delivered webhook is received.

Solution

Check your account status and quality rating in Meta Business Suite. Verify your billing is active and not suspended. Contact Meta support if the issue persists after confirming everything is in order.

Problem

Message cannot be delivered to the recipient.

Solution

Ensure the recipient phone number is valid, the person has an active WhatsApp account, and they have not blocked your business number.

Problem

Too many messages sent in a short time, causing Meta to throttle your account.

Solution

Throttle your sending speed and warm up your number gradually. New numbers start with lower limits that increase as your quality rating improves.

Problem

Messages appear delayed or stuck on the recipient's device.

Solution

This is a Meta-side issue related to end-to-end encryption key exchange. Check WhatsApp's official FAQ for current status. Usually resolves on its own.

Problem

Utility templates are wrongly classified as marketing by Meta, resulting in higher conversation fees.

Solution

Simplify the wording, remove any promotional language, discount codes, or CTAs. Focus on transactional content only (order updates, confirmations). Request re-review after editing.

Problem

Template approval by Meta can take from a few minutes to sometimes more than a day.

Solution

Wait at least 24 hours as review times vary. If stuck longer, duplicate the template and resubmit. Avoid making frequent edits to templates under review as this resets the review process.

Problem

Template translation exceeds the allowed character length.

Solution

Shorten the translated text or reduce the number of dynamic variables. Each language version must fit within Meta's character limits independently.

Problem

Users are reporting or ignoring your messages, leading to reduced sending limits.

Solution

Send only relevant messages to opted-in customers. Avoid spammy content, improve targeting, and make sure your messages provide clear value. Monitor your quality rating in Meta Business Suite regularly.

Problem

Meta limits your sending capability due to suspicious activity or quality issues.

Solution

Wait for the restriction period to end and reduce your sending volume. Focus on improving your quality rating by sending fewer, more targeted messages.

Problem

Permanent restriction due to policy violation or false flag by Meta.

Solution

Appeal to Meta through the Business Help Center. If the appeal is rejected, you will need to use a new phone number and follow Meta's compliance guidelines strictly to avoid future bans.

Problem

The broadcast/campaign feature is disabled when using coexistence mode.

Solution

Use API-based campaigns through Whapi instead of the WhatsApp Business App broadcast feature. Alternatively, switch your setup to full Cloud API mode if you need broadcast capabilities.

Problem

Your system stops receiving delivery reports, message events, or status updates.

Solution

Check your webhook subscription in Meta App Dashboard. Verify the callback URL is accessible, the verification token is valid, and your server is returning 200 OK responses. Check server logs for errors.

Problem

Meta removes your webhook subscription without notice.

Solution

Re-subscribe programmatically and implement monitoring to detect when subscriptions are dropped. This can happen if your endpoint returns errors consistently.

Problem

Things break without clear reason or error logs from Meta.

Solution

Retry the operation, reconnect your account, or wait a few hours. Meta's infrastructure occasionally has temporary issues. If critical, escalate to Meta support with your WABA ID and error details.