🔄 Coexistence Feature (Onboarding WhatsApp Business App Users)
The coexistence feature allows you to configure Embedded Signup so business customers can onboard using their existing WhatsApp Business app account and phone number. Successfully onboarded customers can use your app to message at scale while retaining the ability to send one-to-one messages using the WhatsApp Business app, with messaging history kept in sync between both platforms.
What is Coexistence?
Coexistence allows businesses with existing WhatsApp Business app accounts to seamlessly transition to Cloud API without losing their existing setup. When configured for coexistence:
- Existing Account Integration: Businesses can connect their current WhatsApp Business app phone number to Cloud API
- Dual Messaging Options: Continue using WhatsApp Business app for personal conversations AND use Cloud API for automated messaging
- Message History Sync: Keep messaging history synchronized between both platforms
- QR Code Onboarding: Simple QR code scanning process connects existing accounts
WHY COEXISTENCE IS IMPORTANT
Many businesses already have established WhatsApp Business app accounts with:
- Existing customer conversations and history
- Verified phone numbers and business profiles
- Team members familiar with the WhatsApp Business app interface
- Custom business settings and preferences
Coexistence lets them leverage Cloud API's automation capabilities without losing their existing setup.
How Coexistence Works
Simple process for connecting existing WhatsApp Business app accounts:
For Super Admin (One-time Setup)
Step 1: Enable Required Webhooks
You need to enable specific webhook permissions in your Meta App Dashboard for coexistence to work:
Go to Meta Developer Dashboard
- Visit developers.facebook.com
- Select your App → Products → WhatsApp → Configuration
- Find Webhooks section → Click Edit
Subscribe to These Webhook Fields (check the boxes):
- ✅
messages- Receive customer messages - ✅
message_echoes- Receive messages from WhatsApp Business app - ✅
smb_message_echoes- Required for coexistence - ✅
smb_app_state_sync- Keeps both platforms in sync - ✅
history- Import past conversations (recommended)
- ✅
That's it for admin setup!
For Tenants (Using the Feature)
Step 1: Access Embedded Signup
- Login to your WhatsMarkSaaS tenant panel
- Go to Embedded Signup
- Click "Connect with Facebook" button
Step 2: Meta Popup Opens
- Enter your WhatsApp Business app phone number
- Meta popup will open automatically
- Follow the instructions in the popup
Step 3: Scan QR Code
- Check your WhatsApp Business app for a message
- Tap "Scan QR code" button in the message
- Use your phone camera to scan the QR code
- Choose whether to share message history
Step 4: Complete Setup
- Return to WhatsMarkSaaS panel
- Wait for synchronization to complete
- Start using both platforms together!
Benefits of Coexistence
- Keep Your Existing Setup: No need to abandon your current WhatsApp Business app
- Use Both Platforms: Send personal messages via WhatsApp Business app AND automated messages via WhatsMarkSaaS
- Message History Preserved: Your past conversations stay intact
- Easy Transition: Simple QR code setup process
Requirements
- The business customer must be using WhatsApp Business app version 2.24.17 or higher.
- The business customer's phone number country code must be supported.
- You must already be a Solution Partner or Tech Provider.
- You must know how to use the Cloud API.
- Your webhook callback must be able to successfully accept and process webhooks.
- You must be using Embedded Signup with session logging enabled.
🌍 UNSUPPORTED COUNTRIES
WhatsApp Business account phone numbers from the following countries are NOT supported for coexistence:
- 🇳🇬 Nigeria
- 🇿🇦 South Africa
Visual Guide
Here's what the process looks like for your tenants:
Step 1: Choose Connection Option
Step 2: Enter Phone Number & Get QR Code
Step 3: Check WhatsApp Business App
Step 4: History Sharing Option
Step 5: Scan QR Code
Step 6: Setup Complete!
After scanning, the business is connected and can use both WhatsApp Business app and WhatsMarkSaaS together.
Limitations
- In order to remain compatible with the WhatsApp Business app, business phone numbers that are in use with both the WhatsApp Business app and Cloud API have a fixed throughput of 20 mps.
- If your business customer worked with a partner in the past and still shares the previous credit line, they may see an error when attempting to switch to a new partner. Follow the guide to resolve the error.
Unsupported countries
WhatsApp Business account phone numbers with country codes from the following countries are not supported:
- Nigeria
- South Africa
Pricing
After a business customer has been onboarded to Cloud API:
- Messages sent via the WhatsApp Business app remain free.
- Messages sent via Cloud API are subject to Cloud API pricing.
Refer to the API Solutions for WhatsApp Business App Users Pricing Explainer (PDF) for a detailed breakdown of common pricing scenarios.
Customer service window behavior
- A customer service window opens only when a WhatsApp user messages a business that is already onboarded to Cloud API.
- If a WhatsApp user messages a business just before onboarding, the business can only respond with a template message, since no customer service window was opened.
- Once the business is onboarded and a user sends a new message, a normal service window opens, allowing non-template responses.
Setup Complete
After successful setup, businesses can use both WhatsApp Business app and WhatsMarkSaaS together seamlessly.
⏱️ Synchronization Time
The onboarding and synchronization process can take several minutes, depending on:
- The size of the business’s messaging history
- The business’s internet speed
- How efficiently your system can process incoming webhooks
- Your server performance and data handling capacity
💡 Tip: Use proper job queues and webhook digest systems to prevent delays in large message synchronizations.
Common Issues & Solutions
QR Code Not Working
- Make sure WhatsApp Business app is version 2.24.17 or newer
- Check internet connection on the phone
- Ensure using WhatsApp Business app (not regular WhatsApp)
- Wait a few minutes and try again
Message Not Received in WhatsApp
- Verify phone number includes country code
- Check if WhatsApp Business app is properly installed
- Wait 2-3 minutes for message delivery
Sync Takes Too Long
- Keep WhatsApp Business app open during setup
- Ensure good internet connection
- Contact support if sync exceeds 24 hours
⚠️ Important Implementation Notes
IMPORTANT THINGS TO REMEMBER
Webhook Permissions Must Be Enabled: You need to turn on specific webhook permissions in your Meta App Dashboard, including
message_echoes,smb_message_echoes, andsmb_app_state_sync. Without these, coexistence won't work.24-Hour Time Limit: After a business completes signup, you have only 24 hours to finish importing their data. If you miss this deadline, they'll need to start the signup process over again.
Message Speed Limit: Businesses using coexistence can only send 20 messages per second (instead of higher limits) to keep both WhatsApp Business app and Cloud API working together properly.
Country Restrictions: Businesses with phone numbers from Nigeria and South Africa cannot use the coexistence feature due to Meta limitations.
App Version Required: The business must have WhatsApp Business app version 2.24.17 or newer installed on their phone for coexistence to work.
Some Features Coming Soon: Chat sync and contact sync features are not available yet in this version, but will be added in future updates.
Need More Help?: For the most up-to-date technical information, check the official Meta documentation: Onboarding WhatsApp Business App Users