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.

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

1. 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
2. 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
3. Use a mobile number: For the smoothest experience, use a mobile phone number capable of receiving SMS verification codes
4. Try voice verification: If SMS verification fails, select the voice call option to receive the verification code via a phone call
5. 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.

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

1. Check supported regions: Review Meta's official list of supported countries for the WhatsApp Business API at Meta's documentation
2. 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
3. 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
4. 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
5. 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.

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

1. 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
2. Deregister from the previous provider: Contact the previous BSP and request that they deregister your phone number from their WhatsApp Business API account
3. 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
4. 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
5. Retry registration: Once the deregistration period has passed, restart the Embedded Signup flow in WhatsTeam and register your number again
6. 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

1. Check internet connection: Ensure the phone running WhatsApp Business App has a stable internet connection, preferably on Wi-Fi
2. 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)
3. Force close and reopen: Close the WhatsApp Business App completely and reopen it to trigger a fresh sync attempt
4. 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
5. 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
6. Restart the phone: A full device restart can resolve underlying connectivity or process issues
7. 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

1. 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
2. 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
3. Update WhatsApp Business App: Ensure you are running the latest version of WhatsApp Business App. Coexistence features require the most recent app version
4. 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
5. 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
6. 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
7. 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

1. 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
2. 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
3. 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
4. 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
5. 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
6. Check Page status: Ensure the Facebook Page is published and not restricted. Unpublished or restricted pages cannot be connected to WABA
7. 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

1. Complete pending syncs: Ensure all message syncing between the WhatsApp Business App and the API has completed before attempting to disable Coexistence
2. Check permissions: Verify that your WhatsTeam account has admin-level access to the device settings. Only admin users can enable or disable Coexistence mode
3. Disconnect the app first: On your phone, open WhatsApp Business App and unlink any connected devices before disabling Coexistence in WhatsTeam
4. 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
5. Clear the session: In WhatsTeam, go to the device settings and clear any active sessions before disabling Coexistence
6. 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

1. 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
2. Update all devices: Make sure both the primary phone and the companion device are running the latest version of WhatsApp Business App
3. 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
4. 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
5. 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
6. Verify Coexistence compatibility: Some companion device features may have limited functionality in Coexistence mode. Check WhatsTeam's documentation for the latest compatibility information
7. 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

1. 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
2. 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
3. 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
4. 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
5. 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
6. 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
7. 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
• Meta Business Help Center: Visit Meta's business support for WhatsApp-specific issues
• WhatsApp Business API Documentation: Review the official API documentation for technical details
• Community Forums: Join the WhatsTeam community to connect with other users who may have encountered similar issues