This comprehensive guide outlines the connection options, requirements, step-by-step onboarding flows, asset sharing protocols, and troubleshooting procedures for implementing WhatsApp Coexistence (COEX) via 360dialog. It is designed to assist technical teams and clients in establishing and maintaining seamless WhatsApp Cloud API connections alongside the WhatsApp Business App.
1. Executive Overview: Understanding WhatsApp Coexistence
WhatsApp Coexistence (COEX) enables a business to run the standard WhatsApp Business App (on a physical smartphone) and the WhatsApp Cloud API simultaneously on the exact same phone number.
Key Benefits
- Dual Operating Modes: Staff can continue conversing directly via the mobile app while automated systems (CRMs, AI Chatbots, broadcast campaigns) operate over the API.
- Chat History Retention: Historical chats and contacts from the WhatsApp Business App are preserved during and after onboarding.
- Flexibility: Ideal for teams requiring human touchpoints on mobile devices alongside automated lead routing and API webhooks.
2. Pre-Onboarding Requirements & Prerequisites
Before initiating any onboarding flow, ensure all mandatory prerequisites are met to prevent automated blocks or verification failures by Meta.
| Prerequisite Area | Specific Requirement | Importance & Impact |
|---|---|---|
| Mobile Device & App | Latest WhatsApp Business App installed on a smartphone with a working camera. App version must be v2.24.17 or newer. | Required to scan the onboarding QR code and verify the coexistence connection. |
| Phone Number History | Active usage on WhatsApp Business App with real conversations (minimum 7 days; ideally 30-60 days). | Meta flags newly created or inactive numbers attempting immediate API integration as ineligible. |
| Meta Business Portfolio | Must be owned by the legal business entity. The Business Info section (Legal Name, Address, Website, Phone) must be 100% completed. | Incomplete business info triggers immediate WABA restrictions and account suspension. |
| Live Business Website | Publicly accessible website secured with HTTPS/SSL, clearly stating company operations and services. | Meta Integrity teams review the domain to enforce WhatsApp Business Messaging Policies. |
| Admin Access | Admin privileges in the Meta Business Portfolio and access to 360dialog Hub account. | Required to accept Meta terms, assign asset permissions, and manage billing. |
3. Available Connection Methods & Step-by-Step Onboarding
Connection Method A: New Coexistence Onboarding
Use this method when onboarding a phone number currently active on the WhatsApp Business App that has never been connected to a 360dialog API account or another BSP API.
- Initiate Embedded Signup: Access the 360dialog Hub or Partner App and launch the Embedded Signup (ES). Select your pricing plan and confirm admin permissions.
- Specify Connection Status:
- Select: “No, this number is not connected to the WhatsApp Business API.”
- Select: “Yes, this number is connected to the WhatsApp Business App.”
- Select Meta Business Portfolio & WABA: Choose your verified Meta Business Portfolio. Select an existing WhatsApp Business Account (WABA) or choose Create a WhatsApp Business Account.
- Connect WhatsApp Business App:
- Enter the target phone number.
- Open the WhatsApp Business App on the smartphone.
- Tap the in-app notification prompt or navigate to Settings > WhatsApp > Sign Up with Facebook.
- Scan the displayed QR code or enter the provided numerical access code.
- Sync History & Complete Registration: Confirm chat history migration prompt. Perform OTP verification (SMS or Voice) if prompted, review shared assets, and click Finish.
Connection Method B: Migrating an Existing COEX Number to 360dialog
Use this method if the coexistence number is currently connected to another Business Solution Provider (BSP) or direct Meta API and needs to be migrated to 360dialog.
- Disconnect Old BSP API Connection: On the mobile smartphone, open WhatsApp Business App > Settings > Account > Business Platform > tap Disconnect Account.
- Back Up Chat History: Go to Settings > Chats > Chat Backup and execute a manual backup to Google Drive (Android) or iCloud (iOS).
- Clear Old WABA Credit Line Binding:
- Log into standard WhatsApp Consumer App on the device with the business number and accept chat transfer.
- Re-open WhatsApp Business App, enter the number, and transfer chats back. This completely unlinks the old BSP WABA and payment credit lines.
- Execute COEX Onboarding on 360dialog: Relaunch 360dialog Embedded Signup, select your Meta Business Manager, create a new WABA, and complete the QR code coexistence connection process.
4. Asset Sharing & Partner Permissions
To enable 360dialog to process webhooks and deliver API messages, Meta assets must be shared with full control permissions.
Standard Partner Access Assignment
- 360dialog Business Partner ID: 734443296905665
- Location: Meta Business Suite > Business Settings > Accounts > WhatsApp Accounts > Select WABA > Partners > Assign Partner.
- Permission Level: Grant Full Control / Everything.
Special Rule for Coexistence WABAs
Meta restricts direct partner assignment changes on existing WABAs that contain active Coexistence numbers. If permissions are revoked or show 🔴 BSP PERMISSION REMOVED in 360dialog Hub:
- Do not attempt standard partner assignment in Meta Business Manager.
- Click Fix channel setup in 360dialog Hub to re-trigger Embedded Signup.
- Select the exact same WABA during registration to restore full control permissions.
5. Key Limitations & Operating Guidelines
- 24-Hour Messaging Window: Freeform (Service) messages are restricted to a 24-hour window following customer-initiated messages. Outbound conversations require approved Template Messages.
- Companion Devices: Up to 4 companion devices (WhatsApp Web / Mac Desktop) can be re-linked after onboarding. Unsupported devices (WhatsApp for Windows Native / WearOS) will not trigger API webhooks.
- Official Business Account (Blue Badge): Verification badges do not automatically transfer between WhatsApp Business App and Cloud API. An OBA re-application is required.
- WABA Portability: COEX numbers cannot be directly transferred between WABAs without performing a full disconnection and re-onboarding process.
6. Expected Issues & Troubleshooting Matrix
| Issue / Error Prompt | Root Cause | Recommended Resolution |
|---|---|---|
| Phone number is not eligible | Number is newly created, lacks active chat history, or is bound to an un-deleted old WABA setup. | Maintain active, daily usage on WhatsApp Business App for 7–30 days. Delete any orphaned WABA configurations in Meta Business Manager. |
| BSP PERMISSION REMOVED | User logged out of primary mobile phone, disconnected in app, or account experienced a temporary ban. | Relaunch 360dialog Embedded Signup via the “Fix channel setup” button and select the original WABA to re-establish partner control. |
| Chat sync failure / Stuck loading | Unstable network, outdated app version, or WhatsApp Business App closed during QR sync. | Update app to v2.24.17+, keep phone unlocked with app in foreground on high-speed Wi-Fi during initial QR scan. |
| Two-factor authentication (2FA) error | 2FA is active on the source WABA in Meta Business Settings. | Navigate to Meta Business Manager > WhatsApp Manager > Phone Numbers > Settings > Two-step verification and disable 2FA prior to migration. |
| QR Code fails to appear / scan | Camera hardware issue, lighting, or outdated Meta Business Suite / WA app version. | Ensure clean camera lens, update WhatsApp Business App, and navigate directly to Settings > WhatsApp > Sign Up with Facebook. |