WhatsApp Business API Connection: How to Solve Common Issues (2026)
Troubleshooting guide for WhatsApp Coexistence setup — phone eligibility, regional restrictions, syncing delays, QR code problems, and more.
W
WhatsTeamMarch 23, 2026
Share this article:
WhatsApp Business API Troubleshooting: Common Setup Issues and Solutions
Setting up WhatsApp Business API with Coexistence mode can sometimes present challenges. This troubleshooting guide covers the most common issues you may encounter during the onboarding process with WhatsTeam, along with their root causes and step-by-step resolution instructions.
1. Phone Number Eligibility
Issue Symptom
During the Embedded Signup flow, you receive an error message stating that your phone number is not eligible for registration with the WhatsApp Business API. The number is rejected during the verification step, and you cannot proceed with the onboarding process.
Screenshot showing the phone number not eligible error message in the WhatsApp Business Platform signup
Root Cause
Not all phone numbers are eligible for WhatsApp Business API registration. Common reasons include:
The phone number is already registered with another WhatsApp Business API provider (BSP)
The phone number is a landline that cannot receive SMS or voice calls for verification
The phone number has been previously banned or flagged by WhatsApp
The number format is incorrect or includes invalid country codes
The number is a virtual number from an unsupported VoIP provider
Resolution Steps
Verify number format: Ensure the phone number is entered in full international format, including the country code (e.g., +1 for US, +34 for Spain), without any leading zeros after the country code
Check existing registrations: If the number was previously registered with another BSP, you must first deregister it from the old provider before registering with WhatsTeam
Use a mobile number: For the smoothest experience, use a mobile phone number capable of receiving SMS verification codes
Try voice verification: If SMS verification fails, select the voice call option to receive the verification code via a phone call
Contact support: If the number was previously banned or you continue to experience issues, contact WhatsTeam support with your phone number details so we can investigate further with Meta
2. Regional Restrictions
Issue Symptom
When attempting to register your phone number, you see an error indicating that your country or region is not supported for WhatsApp Business API registration. The Embedded Signup flow blocks the registration at the phone number entry step.
Screenshot showing the region not supported error when the country prefix is unsupported for Coexistence
Root Cause
WhatsApp Business API is not available in all countries and regions. Meta maintains a list of supported markets, and phone numbers with country prefixes from unsupported regions cannot be registered. Additionally, certain sanctions or regulatory restrictions may prevent API access in specific countries.
Resolution Steps
Check supported regions: Review Meta's official list of supported countries for the WhatsApp Business API at Meta's documentation
Use an alternative number: If your primary country is not supported, consider using a phone number from a supported region where your business has a presence
Verify country code: Double-check that you are entering the correct country code for your number. An incorrect country code may trigger a regional restriction error even if your actual country is supported
Check for recent additions: Meta regularly expands its supported regions. If your country was recently added, try again or clear your browser cache before retrying
Contact WhatsTeam support: If you believe your region should be supported but are still experiencing issues, reach out to our support team for assistance
3. Previous WABA Usage
Issue Symptom
During registration, you receive an error stating that your phone number is already associated with a WhatsApp Business Account (WABA). The system prevents you from completing the registration because the number has a prior API association.
Screenshot showing the error that the number is registered to an existing WhatsApp account
Root Cause
A phone number can only be associated with one WhatsApp Business API account at a time. If the number was previously used with:
Another BSP (Business Solution Provider)
A different Meta Business Manager account
A self-hosted WhatsApp Business API deployment
A previous WhatsTeam account that was not properly deregistered
The number remains locked to that previous association until it is formally deregistered.
Resolution Steps
Identify the previous provider: Determine which BSP or platform previously had your number registered. Check your Meta Business Manager account for any existing WABA associations
Deregister from the previous provider: Contact the previous BSP and request that they deregister your phone number from their WhatsApp Business API account
Remove from Meta Business Manager: If you have access to the Meta Business Manager where the number was registered, navigate to the WhatsApp Manager section and delete the phone number
Wait for propagation: After deregistration, wait at least 24 hours before attempting to register the number again. In some cases, it may take up to 48 hours for the deregistration to fully propagate
Retry registration: Once the deregistration period has passed, restart the Embedded Signup flow in WhatsTeam and register your number again
Escalate if needed: If the number remains locked after 48 hours, contact WhatsTeam support with proof of ownership, and we will escalate the issue directly with Meta
4. Syncing Delays
Issue Symptom
After completing the Embedded Signup and enabling Coexistence mode, your WhatsApp Business App does not reflect the API connection. Contacts, messages, or business profile information are not syncing between the WhatsApp Business App and the API. The Coexistence status appears as "Pending" for an extended period.
Root Cause
Syncing between the WhatsApp Business App and the Cloud API can experience delays due to:
Network connectivity issues on the phone running WhatsApp Business App
Large volumes of existing contacts or messages that need to sync
Server-side processing delays on Meta's infrastructure
The WhatsApp Business App is running an outdated version
Background app restrictions on the phone preventing sync
Resolution Steps
Check internet connection: Ensure the phone running WhatsApp Business App has a stable internet connection, preferably on Wi-Fi
Update the app: Make sure you are running the latest version of WhatsApp Business App from the App Store (iOS) or Google Play Store (Android)
Force close and reopen: Close the WhatsApp Business App completely and reopen it to trigger a fresh sync attempt
Disable battery optimization: On Android, go to Settings > Battery > Battery Optimization and disable it for WhatsApp Business App. On iOS, ensure Background App Refresh is enabled for the app
Wait patiently: Initial sync can take up to 24 hours for accounts with large contact lists or message histories. Allow sufficient time before considering the sync as failed
Restart the phone: A full device restart can resolve underlying connectivity or process issues
Re-enable Coexistence: If syncing still fails after 24 hours, try disabling and re-enabling Coexistence mode through WhatsTeam. Navigate to the device settings, disable Coexistence, wait 5 minutes, then enable it again
5. QR Code Problems
Issue Symptom
During the Coexistence setup, you are asked to scan a QR code with your WhatsApp Business App, but the QR code does not load, has expired, or the app does not recognize it. Scanning the QR code results in an error or no response.
Root Cause
QR code issues during Coexistence setup typically occur due to:
The QR code has expired (QR codes are time-limited and must be scanned within a few minutes)
Browser or app caching is showing an old or invalid QR code
The WhatsApp Business App version does not support Coexistence QR scanning
Camera permissions are not enabled for the WhatsApp Business App
The QR code is being scanned with the wrong app (regular WhatsApp instead of WhatsApp Business)
Resolution Steps
Refresh the QR code: Click the refresh button on the QR code screen in WhatsTeam to generate a new, valid QR code. QR codes expire after approximately 60 seconds
Clear browser cache: Clear your browser cache or try opening the WhatsTeam dashboard in an incognito/private browsing window to ensure you see a fresh QR code
Update WhatsApp Business App: Ensure you are running the latest version of WhatsApp Business App. Coexistence features require the most recent app version
Check camera permissions: On your phone, verify that WhatsApp Business App has permission to access the camera. Go to your phone's Settings > Apps > WhatsApp Business > Permissions > Camera
Use the correct app: Make sure you are scanning the QR code with WhatsApp Business App, not the regular WhatsApp app. Coexistence mode is only available on WhatsApp Business App
Try a different device: If the camera on your primary device is having issues, try scanning the QR code with a different device that has the same WhatsApp Business account
Check lighting and display: Ensure your computer screen brightness is sufficiently high and that there is no glare on the screen that could interfere with QR code scanning
6. Facebook Page Connection Errors
Issue Symptom
During the Embedded Signup flow, you encounter an error when trying to connect your WhatsApp Business Account to a Facebook Business Page. The system either shows no available pages, displays a permissions error, or fails to establish the connection between your WABA and the Facebook Page.
Root Cause
Facebook Page connection errors typically arise from:
You do not have admin access to the Facebook Page you are trying to connect
The Facebook Page is already connected to a different WhatsApp Business Account
Your Meta Business Manager does not have ownership of the Facebook Page
There is a mismatch between the Meta Business Manager used for WABA and the one managing the Facebook Page
The Facebook Page has restrictions or has been unpublished
Resolution Steps
Verify page admin access: Confirm that your Facebook account has admin-level access to the Page you want to connect. Go to the Facebook Page > Settings > Page Roles to verify
Check existing connections: In Meta Business Manager, navigate to Business Settings > Accounts > WhatsApp Accounts to see if the Page is already linked to another WABA. Disconnect it from the other account first
Use the correct Business Manager: Ensure you are logged into the same Meta Business Manager account that owns both the Facebook Page and the WABA you are setting up
Claim the Page: If the Page is not yet part of your Meta Business Manager, go to Business Settings > Accounts > Pages > Add and claim ownership of the Page
Create a new Page: If you cannot resolve permissions on an existing Page, create a new Facebook Business Page through Meta Business Manager and use it for your WABA connection
Check Page status: Ensure the Facebook Page is published and not restricted. Unpublished or restricted pages cannot be connected to WABA
Contact Meta support: If none of the above steps resolve the issue, contact Meta Business Support through your Meta Business Manager for assistance with Page connection issues
7. Disabling Coexistence
Issue Symptom
You want to disable Coexistence mode to use the WhatsApp Business API independently (without the WhatsApp Business App connected), but the option to disable is grayed out, produces an error, or the process does not complete successfully.
Root Cause
Disabling Coexistence can fail due to:
There are active conversations or pending messages being processed through the WhatsApp Business App
The WhatsApp Business App has not been properly disconnected from the phone
A system-level lock is in place while syncing is still in progress
Insufficient permissions in WhatsTeam to modify device settings
API rate limits or temporary service restrictions from Meta
Resolution Steps
Complete pending syncs: Ensure all message syncing between the WhatsApp Business App and the API has completed before attempting to disable Coexistence
Check permissions: Verify that your WhatsTeam account has admin-level access to the device settings. Only admin users can enable or disable Coexistence mode
Disconnect the app first: On your phone, open WhatsApp Business App and unlink any connected devices before disabling Coexistence in WhatsTeam
Wait and retry: If the system shows a sync in progress, wait at least 30 minutes before trying again. Attempting to disable during an active sync can cause errors
Clear the session: In WhatsTeam, go to the device settings and clear any active sessions before disabling Coexistence
Contact support: If the disable option remains unavailable or continues to error, contact WhatsTeam support. In some cases, Coexistence may need to be disabled from Meta's backend, which requires our team to coordinate with Meta
8. Companion Device Incompatibility
Issue Symptom
After enabling Coexistence mode, you attempt to use WhatsApp Business App on a companion device (such as a tablet or secondary phone), but the companion device cannot connect, shows errors, or does not receive messages properly.
Root Cause
Coexistence mode has specific limitations regarding companion devices:
WhatsApp Business App companion device support is limited to certain device types and OS versions
The primary device must remain connected and active for companion devices to function
There is a maximum number of companion devices allowed (typically 4)
Some companion device features may not be fully compatible with Coexistence mode
The companion device may be running an outdated version of WhatsApp Business App
Resolution Steps
Check device compatibility: Ensure your companion device meets WhatsApp's minimum requirements. For Android, version 5.0 or later is required. For iOS, version 15.1 or later is required
Update all devices: Make sure both the primary phone and the companion device are running the latest version of WhatsApp Business App
Keep primary device online: The primary phone must remain connected to the internet for companion devices to function. If the primary device goes offline for more than 14 days, companion devices will be disconnected
Check companion device limits: WhatsApp allows up to 4 companion devices. If you have reached the limit, unlink an existing companion device before adding a new one
Relink the companion device: Remove the companion device from WhatsApp Business App (Settings > Linked Devices) and set it up again by scanning the QR code from the primary device
Verify Coexistence compatibility: Some companion device features may have limited functionality in Coexistence mode. Check WhatsTeam's documentation for the latest compatibility information
Test without Coexistence: Temporarily disable Coexistence to determine if the companion device issue is related to Coexistence specifically or is a general WhatsApp connectivity problem
9. Post-Onboarding Name Changes
Issue Symptom
After completing the WhatsApp Business API onboarding process, you want to change your business display name but the change is rejected by Meta, takes an extended time to process, or does not appear on your WhatsApp profile.
Root Cause
WhatsApp Business API display name changes are subject to Meta's review and approval process:
Meta enforces strict naming guidelines for business display names
Name changes require re-review and approval, which can take up to 72 hours
Names that violate Meta's naming policies will be rejected
Frequent name changes may trigger additional scrutiny or delays
The display name must match the business name associated with your Meta Business Manager
Resolution Steps
Review naming guidelines: Before submitting a name change, review Meta's display name guidelines. Names must represent your business accurately and cannot include:
Generic terms without your business name
All capital letters (unless it is an acronym)
Misleading or deceptive names
Personal names (unless the business is named after a person)
Excessive punctuation or special characters
Submit through WhatsTeam: Navigate to your device settings in WhatsTeam and update the business display name. The change will be submitted to Meta for review
Wait for approval: Name changes typically take 24 to 72 hours for Meta to review. Do not submit multiple change requests during this period, as it may delay the review further
Verify business information: Ensure your Meta Business Manager business information matches the display name you are requesting. Discrepancies between your business registration and display name can cause rejections
Provide supporting documents: If your name change is rejected, you may need to provide additional documentation such as business registration certificates, trademark registrations, or domain ownership proof
Use an alternative name: If your preferred name continues to be rejected, consider variations that still represent your business while complying with Meta's guidelines
Contact support: If your name change has been pending for more than 72 hours or has been rejected without clear reason, contact WhatsTeam support and we will escalate the review with Meta
Getting Additional Help
If you continue to experience issues that are not covered in this troubleshooting guide:
WhatsTeam Support: Contact our support team through the platform's live chat or email
Step-by-step guide to migrating your WhatsApp number to the official Business API using WhatsTeam, including requirements, limitations, and troubleshooting.