Meta last week published a formal announcement calling on developers to migrate their business customer onboarding flows from embedded signup v2 and v3 to the newly available v4, ahead of a hard deprecation date of October 15, 2026. The post, authored by Keilani Collins and published on May 14, 2026, on Meta for Developers, outlines what changes, what stays the same, and - critically - which integrations cannot be automatically upgraded.

For the marketing technology community, the announcement carries practical weight. Embedded signup is the mechanism through which solution partners and technology providers onboard business clients onto Meta's Business Messaging APIs. That means the migration timeline is not an abstract developer concern; it touches every platform and agency workflow that involves WhatsApp, Instagram, or Messenger as a customer communication channel.

What embedded signup v4 actually changes

The central design shift in v4 is the move from version-specific onboarding flows to a configuration-driven architecture. Under v2 and v3, developers selected a signup version directly. Under v4, the version is no longer a selectable parameter at all. Instead, the Facebook Login for Business Configuration drives the logic. Developers create a configuration in their app dashboard, select which Business Messaging APIs to include, and the flow automatically runs v4.

This is a meaningful structural change. Configuration-level management replaces code-level version selection, which shifts a substantial portion of the integration work out of the codebase and into Meta's own tooling. According to Meta's developer documentation, the full upgrade process - including testing and implementation - is estimated to take up to one week. In simpler cases, the configuration steps alone can be completed in minutes.

V4 also consolidates what were previously separate onboarding flows into a single experience. Businesses onboarding to WhatsApp, Instagram, and Messenger Business Messaging can now do so through one unified flow rather than separate integrations per API. Asset selection, business information, and permissions are each presented on a single page. Phone numbers are auto-linked to Facebook Pages when onboarding to Click-to-WhatsApp ads via the Marketing API - a step that previously required additional manual configuration.

The products supported under v4

The list of supported products in v4 is broader than in prior versions. According to the developer documentation, the following products are available within a single onboarding flow:

Cloud API for WhatsApp enables businesses to send and receive messages at scale, automate workflows, and access advanced messaging features. The required permissions are whatsapp_business_management and whatsapp_business_messaging.

Click to WhatsApp Ads (CTWA) connects the Marketing API with WhatsApp messaging initiation. Required assets include WhatsApp Business accounts, Facebook Pages, and ad accounts, alongside four advertising-specific permissions: ads_read, ads_management, pages_manage_ads, pages_read_engagement, and pages_show_list.

Click to Messenger Ads (CTM) operates similarly but routes users to Facebook Messenger conversations. The asset and permission requirements overlap substantially with CTWA, minus the WhatsApp Business account requirement.

Click to Instagram Direct Ads (CTD) adds Instagram accounts to the required asset set, alongside Facebook Pages and ad accounts. The instagram_manage_events permission is required for the Conversions API variant.

Conversions API is now available across all three messaging channels - WhatsApp, Instagram, and Messenger - enabling businesses to track and optimise messaging interactions with enhanced measurement. For CTWA, the required permission is whatsapp_business_manage_events; for CTM, it is page_events; for CTD, instagram_manage_events.

Marketing Messages API for WhatsApp and Automatic Events API round out the supported product set. The latter notifies applications about key events occurring through Click-to-WhatsApp ads.

V4 also continues to support WhatsApp Business app user onboarding via the feature_type parameter, and Partner-led Business Verification (PLBV) for approved Select Solution or Premier Solution Partners.

This breadth matters for marketing professionals building omnichannel customer journeys. Meta has steadily expanded its business messaging infrastructure, adding Calling API capabilities in July 2025 and enhanced Marketing Messages on Messenger that same month. V4's consolidated onboarding architecture is designed to accommodate that growing product surface without requiring developers to build separate integration flows for each new capability.

Three feature types that cannot be automatically migrated

The most operationally significant detail in the announcement concerns a subset of v2 integrations that will not be automatically upgraded after the October 15 deadline. According to Meta's announcement, most integrations still running on v2 or v3 after deprecation will be automatically converted to v4. However, three specific feature types are excluded from that automatic path:

  • only_waba_sharing
  • marketing_messages_lite
  • coex

Developers using any of these feature types with v2 must complete a manual upgrade before October 15, 2026. After that date, according to the announcement, "the deprecated feature types will no longer function; they will default to the standard embedded signup flow." That means integrations relying on these configurations will break - not merely degrade - if left unmigrated.

The coex feature type relates to Coexistence onboarding, which handles scenarios where a business is migrating from the WhatsApp Business app to the Cloud API while maintaining continuity. The only_waba_sharing type limits the onboarding scope to WhatsApp Business Account asset sharing only. The marketing_messages_lite type relates to a lighter-weight marketing messages configuration. None of these map cleanly to v4's unified product selection model, which is why automatic migration is not possible.

For agencies and platform vendors with many client accounts, identifying which integrations use these feature types is a necessary first step before any upgrade work begins.

How the upgrade process works

According to Meta's step-by-step guidance, the upgrade involves four main actions. First, the developer navigates to their app on developers.facebook.com and selects Configurations under Facebook Login for Business, then creates a new configuration and names it. Second, they select the WhatsApp Embedded Signup login variation. Third, they select which Business Messaging APIs to include in the onboarding flow. Fourth, they copy the configuration ID for use inside the Facebook Login SDK.

Testing happens through the Embedded Signup Builder. The developer selects the new configuration, opens the flow - without needing to select a version, since the configuration drives that logic - and clicks Login with Facebook to preview the v4 experience. Meta's documentation notes that no version selection is required at this stage, which is a departure from the prior workflow.

One notable change affects the Facebook Login SDK call. Under v2 and v3, integrations passed a version parameter directly. Under v4, that parameter is replaced by the configuration ID. This is the primary code-level change required. The rest of the upgrade is largely configuration rather than implementation work.

What this means for marketing technology workflows

For marketing professionals and their technology partners, embedded signup is the entry point to Meta's business messaging ecosystem. Any platform that enables clients to self-onboard to WhatsApp Business, Messenger, or Instagram messaging without leaving the platform interface depends on embedded signup. Marketing API tools that enable Click-to-WhatsApp advertising and conversational commerce workflows sit downstream of this onboarding layer.

The introduction of a unified flow for multiple APIs is significant for onboarding user experience. Previously, a business setting up WhatsApp Cloud API and Click-to-WhatsApp ads might encounter two separate flows with overlapping but distinct permission requests. V4 consolidates those into a single session. The announcement states that asset selection, business information, and permissions are each consolidated onto a single page - a reduction in the number of screens and steps compared to prior versions.

The Facebook Login for Business Configuration interface also gives developers a single place to evolve their integration over time. New Business Messaging APIs can be added to an existing configuration without rebuilding the underlying flow from scratch. That flexibility is relevant given Meta's pace of product launches in this category. Meta launched utility messages on Messenger in July 2025 and expanded marketing messages to 21 countries the same month. V4's architecture is designed to accommodate those expansions without forcing a full integration rebuild each time.

For the Conversions API specifically, v4's permissions table is explicit. The whatsapp_business_manage_events scope is required for CTWA measurement, while instagram_manage_events covers CTD. These are Advanced Access permissions, meaning developers must request and receive approval for them through Meta's App Review process before going live. The announcement notes that v4 will automatically select all necessary permissions when products are chosen, but Advanced Access must still be obtained separately.

The competitive and regulatory context

This onboarding infrastructure update lands against a backdrop of significant regulatory and competitive pressure on Meta's messaging platforms. The European Commission has been pushing Meta toward interim measures over its WhatsApp AI lockout, a case registered under AT.41034 that centres on Meta's decision to restrict third-party general-purpose AI assistants from the platform while maintaining Meta AI as the sole option. For developers building on the Business Messaging APIs, that regulatory environment adds an additional layer of uncertainty to long-term integration planning.

At the same time, Meta's 2026 DMA compliance report confirmed the imminent arrival of WhatsApp advertising in the EU, opening WhatsApp Status and Channels as paid media placements in a market where the platform had previously been closed to advertising. That expansion makes the onboarding infrastructure underlying Click-to-WhatsApp ads more consequential for advertisers operating in European markets.

The V4 documentation release date of October 8, 2025 is also notable. The documentation predates the blog post by more than six months, suggesting Meta has been updating the technical specification progressively while preparing a more visible push for developer adoption ahead of the deprecation window.

Timeline

  • October 8, 2025: Embedded signup v4 documentation released, marking the official v4 release date
  • December 12, 2025: Developer documentation updated with additional detail
  • May 14, 2026: Meta for Developers publishes migration announcement by Keilani Collins, urging developers to upgrade before the October deadline
  • May 15, 2026: Meta Developers publishes YouTube tutorial walkthrough on migrating to v4 before the deprecation deadline
  • October 15, 2026: Embedded signup v2 and v3 deprecation date; only_waba_sharing, marketing_messages_lite, and coexfeature types cease functioning

Related PPC Land coverage:

Summary

Who: Meta for Developers, targeting solution partners, independent software vendors, and technology providers using embedded signup v2 or v3 to onboard business clients onto Meta's Business Messaging APIs.

What: The release of embedded signup v4, which consolidates WhatsApp, Instagram, and Messenger business onboarding into a single, configuration-driven flow using Facebook Login for Business, alongside the announced deprecation of v2 and v3 on October 15, 2026. Three feature types - only_waba_sharing, marketing_messages_lite, and coex - cannot be automatically migrated and require manual developer action before the deadline.

When: The v4 documentation was released on October 8, 2025. The migration announcement was published on May 14, 2026. The deprecation deadline is October 15, 2026. Meta estimates up to one week of developer effort to complete the full upgrade including testing.

Where: The upgrade affects integrations built on Meta's developer platform at developers.facebook.com, impacting any application that uses embedded signup to onboard businesses onto WhatsApp Cloud API, Click-to-WhatsApp, Click-to-Messenger, Click-to-Instagram Direct, Conversions API for messaging, or Marketing Messages API for WhatsApp.

Why: Meta is retiring v2 and v3 to standardise its developer infrastructure around a configuration-driven model that supports a broader set of Business Messaging products from a single onboarding flow. The shift reduces integration complexity for developers, enables future API additions without full rebuilds, and aligns with Meta's broader business messaging expansion - including Conversions API for all three messaging channels, auto-linking of phone numbers to Facebook Pages for CTWA ads, and asset sharing across business portfolios.

Share this article
The link has been copied!