WhatsApp Embedded Signup v4 Migration: A Coexistence Checklist Before October 15, 2026
If your integration onboards existing WhatsApp Business app numbers through Coexistence, migrate Embedded Signup v2 to v4 before October 15, 2026. Meta requires a new Facebook Login for Business configuration for v4; selecting Embedded Signup and the required products moves the flow to v4. Treat this as an onboarding migration, not a cosmetic interface update: retest permissions, callbacks, Coexistence selection, webhooks, and history synchronization.
Key takeaways
- Meta says Embedded Signup v2 will be deprecated on October 15, 2026, and recommends moving to v4 before that date to avoid disruption.
- V4 is configured through a new Facebook Login for Business configuration. Product selection determines the assets and permissions included in the flow.
- WhatsApp Business app user onboarding—the flow commonly called Coexistence—remains supported in v4.
- A successful migration must prove more than “the dialog opens”: verify the Coexistence option, the finish callback, asset IDs, token exchange, webhook delivery, and the 24-hour history-sync window.
- Teams that do not need the official Business app and Cloud API to share one number should decide whether Coexistence is necessary before investing in the migration.
What changes in the WhatsApp Embedded Signup v4 migration
Meta’s v4 documentation says v4 was released on October 8, 2025 and now replaces v2 as the current Embedded Signup path. The most important implementation change is where the flow is defined.
In v2, important flow choices lived in the extras object passed by the integration. In v4, Meta tells developers to create a new Facebook Login for Business configuration, choose Embedded Signup as the login variation, and select the products the flow should include. The selected products automatically determine v4 and preselect their required assets and permissions.
That changes the migration surface:
| Migration area | What to verify in v4 | Why it matters |
|---|---|---|
| Login configuration | A newly created Facebook Login for Business configuration uses the Embedded Signup variation | Reusing an old v2 configuration is not the documented v4 path |
| Products | Cloud API and any additional messaging products are intentionally selected | Product selection determines the onboarding experience and required assets |
| Permissions | Every automatically selected permission has Advanced Access | A correct-looking dialog can still fail when the app lacks permission access |
| Coexistence | The flow offers connection of an existing WhatsApp Business app account and number | A default Cloud API flow is not proof that Business app onboarding survived the migration |
| Session result | The finish event, asset IDs, and exchangeable token code reach the spawning window | Your backend still needs the result to complete onboarding |
| Webhooks | History, state-sync, and message-echo payloads are accepted | Coexistence depends on synchronization after signup, not signup alone |
V4 also consolidates asset selection, business information, and permissions, and can include products such as Click to WhatsApp Ads and Conversions API. Those additions are optional for a Coexistence-only migration. Select only the products your integration actually supports; a broader dialog creates more permission and testing work.
Does Embedded Signup v4 still support WhatsApp Coexistence?
Yes. Meta’s updated Business app onboarding guide explicitly says WhatsApp Business app user onboarding remains supported. That guide calls the feature “Coexistence” in support and partner documentation.
The official pages need to be read together. The generic versions guide shows an intentionally empty extras object for v4, while the specialized Coexistence guide still documents the whatsapp_business_app_onboarding feature selection and a session-info version. Do not assume that removing every Coexistence-specific setting from an existing launcher will preserve the same flow. Build the new v4 configuration, follow the current Business app onboarding instructions, and validate the actual screen and callback in a test account.
The expected user path is specific: the business chooses to connect an existing WhatsApp Business app account, enters its current number, confirms the connection inside the Business app, and completes Embedded Signup. Afterward, the Business app can continue handling one-to-one messages while Cloud API messages and supported history are synchronized.
If your team is still deciding whether it needs that two-surface workflow, read the existing WhatsApp Coexistence decision guide first. The migration is worthwhile only when people genuinely need the Business app and an official Cloud API integration on the same number.
Coexistence migration checklist
1. Inventory every v2 entry point
Find each production and staging button, SDK call, configuration ID, callback handler, and feature flag that can launch Embedded Signup. Record which customer segment uses Coexistence and which uses the default Cloud API flow. A shared launcher can hide a Coexistence regression until a real Business app user reaches it.
2. Create a new v4 configuration
In App Dashboard → Facebook Login for Business → Configurations, create a configuration, select Embedded Signup, choose the required products, and copy the new configuration ID into the integration. Meta says selecting the products sets the experience to v4.
Check the automatically selected assets and permissions. For Cloud API, the v4 table lists WhatsApp Business accounts plus whatsapp_business_management and whatsapp_business_messaging, both requiring Advanced Access.
3. Re-enable and test the Coexistence path
Use Meta’s current Business app onboarding instructions for the specialized flow. In a test run, confirm that the old WABA-only selection screen is replaced by the option to connect an existing WhatsApp Business account. If that option is missing, stop the rollout; you are testing a different onboarding intent.
Also confirm the documented prerequisites: the customer uses WhatsApp Business app 2.24.17 or later, your organization is a Solution Partner or Tech Provider, your callback can process the required webhooks, and session logging is enabled.
4. Verify the finish callback and onboarding state
The Coexistence guide documents the finish event as FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING. Capture the returned WABA ID, asset IDs, and exchangeable token code, then complete the normal customer-onboarding steps while skipping phone-number registration because the number is already registered.
Do not confuse the session payload’s documented version: 3 with the Embedded Signup configuration version. Treat them as separate contracts and assert both in tests instead of routing solely on one numeric field.
After onboarding, query the business phone number fields Meta documents for this check. The expected state is is_on_biz_app: true with platform_type: "CLOUD_API".
5. Prove all three synchronization paths
Before launch, subscribe the app to the additional WABA webhook fields required by Coexistence:
historyfor prior messages the customer chose to share;smb_app_state_syncfor current and changed contacts;smb_message_echoesfor new messages sent from the WhatsApp Business app.
Meta gives the partner 24 hours after onboarding to initiate contact and message-history synchronization. Each initiation can be performed only once; repeating it requires the customer to offboard and complete the flow again. Store the returned request_id, accept large webhook batches quickly, and process them asynchronously.
6. Roll out with a real rollback boundary
Run v2 and v4 configurations side by side for a controlled cohort while Meta still allows both. Track completion rate, callback receipt, token exchange, is_on_biz_app, synchronization completion, and webhook errors separately by configuration ID. Roll back the entry point—not completed customer state—if v4 fails a gate.
The October deadline is close enough that a late all-at-once cutover is unnecessary risk. Finish the technical migration first, then review the separate WhatsApp service-message measurement plan so onboarding and pricing changes do not become one release.
Where UnifyPort fits
UnifyPort does not migrate Meta configurations, grant Cloud API permissions, synchronize official Business app history, or preserve Meta’s Coexistence status. If your product needs those official capabilities, v4 is the correct path and the migration is mandatory for the integration owner.
UnifyPort fits a different requirement: connecting an ordinary WhatsApp account and receiving supported inbound messages as the standard message.received webhook event. Its WhatsApp authorization supports QR-code and phone-number pairing, and signed webhook delivery uses X-Device-Timestamp, X-Device-Signature, and the endpoint’s signing_secret.
That alternative is relevant when the real goal is an inbound queue rather than a shared Business app plus Cloud API number. Compare the three approaches in the WhatsApp inbound paths guide before committing engineering time to a migration whose official features you may not need.
Limitations and trade-offs
Embedded Signup v4 is the right answer for Solution Partners and Tech Providers that onboard customers to official Cloud API products. It is also the only path in this comparison that preserves Meta’s supported Coexistence behavior, history-sharing flow, official asset model, and Cloud API product permissions.
An unofficial interface cannot supply those privileges. It also cannot make a business eligible for Meta products, replace Meta’s customer-service windows, or turn an ordinary account connection into a Cloud API WABA. Its narrower benefit is a standard inbound interface without requiring a customer to use the official Coexistence stack.
V4 migration also does not remove the operating limits documented for Coexistence. Meta currently lists a fixed 20 messages-per-second throughput for numbers used by both the Business app and Cloud API, separate Cloud API pricing for API-sent messages, unsupported group-history synchronization, and specific companion-device limits. Recheck those constraints against the official guide during acceptance testing.
FAQ
When is Embedded Signup v2 deprecated?
Meta says Embedded Signup v2 will be deprecated on October 15, 2026. Integration owners should move to v4 before that date to avoid onboarding disruption.
Does every WhatsApp Business app user need to migrate?
No. The migration belongs to the partner or provider that owns an Embedded Signup v2 integration. A business that only uses the standalone WhatsApp Business app does not maintain an Embedded Signup configuration.
Does v4 remove WhatsApp Coexistence?
No. Meta says WhatsApp Business app user onboarding continues to be supported in v4. The migration must preserve and test the specialized Coexistence selection rather than assuming the default Cloud API flow is equivalent.
Do I need a new Facebook Login for Business configuration?
Yes. Meta’s v4 guide instructs developers to create a new configuration, select Embedded Signup as the login variation, and choose the products to include.
What should a migration test prove?
At minimum: the existing Business app connection option appears; the finish callback and assets are returned; token exchange completes; is_on_biz_app is true with platform_type set to CLOUD_API; and the history, smb_app_state_sync, and smb_message_echoes webhook paths work.
Next step
If you own a Meta Embedded Signup integration, create the new configuration using the official v4 migration guide and run the checklist above in staging. If you only need ordinary-account inbound messaging, use the UnifyPort WhatsApp authorization guide to evaluate that separate path before building Coexistence.
Sources
Official Meta sources checked on 2026-07-16: