Connecting an Existing WhatsApp Business Number to Vonage via Embedded Sign-Up(Phone Migration no longer supported)

Objective

This guide explains how to share your existing WhatsApp phone number with Vonage when it is currently registered with another WhatsApp Business Solution Provider (BSP).

Looking to onboard a new WhatsApp number instead? See the Getting Started with Vonage's WhatsApp Business API: New V4 Embedded Sign-Up flow guide.

Applies To

• Connecting a WhatsApp Phone number with Vonage via Embedded sign-up flow
• Messages API

Overview

Under Meta's new account model, phone number migration between Solution Partners is not supported. (Refer to Meta Docs)

Instead, the WhatsApp Account (WAAC) that owns the number is shared with Vonage — giving Vonage access to the number without any migration. 

Vonage will have its own dedicated Messaging Account (Paid Messaging Account-PMA) created under your WAAC, keeping billing and templates isolated from your other BSPs.

• Your phone number stays in place

• Conversations are uninterrupted

• Your existing BSP setup is not affected

• Sharing is additive — you decide whether to keep or remove your previous BSP

How to Check if Your Account is on the New Account Model

To check if your account is on the new account model, go to Meta Business Suite > Settings and look under Accounts — if you see both WhatsApp Accounts and Messaging Accounts listed separately, your account is on the new (dual) account model. If you only see WhatsApp Accounts, your account has not yet been migrated and you can follow the How to Migrate a WhatsApp Phone Number article instead.

Before You Begin

Make sure you have the following ready:

• An active Meta Business Portfolio with your existing WhatsApp Account (WAAC) and phone number

• Admin access to your Meta Business Portfolio

• A Vonage API account — sign up here if you do not have one

How It Works

When you complete the Embedded Sign-Up (ESU) flow on the Vonage Dashboard with your existing phone number:

1. Meta identifies the WhatsApp Account (WAAC) your number is already associated with

2. The WAAC is automatically pre-selected in the ESU flow — you do not need to select it manually

3. A new Messaging Account (PMA) is created for Vonage under your existing WAAC

4. Vonage is added as an additional BSP on your number — however, since Vonage does not currently support Meta's Thread Control (the protocol that allows multiple BSPs to manage conversations simultaneously), having the previous BSP still active can interfere with inbound message delivery to Vonage even after updating Conversation Routing. It is strongly recommended to remove the previous BSP from both the Messaging Account and the WhatsApp Account once your number is successfully shared with Vonage and connected — see Step 10 for the exact steps to do this. 

   Note: Thread Control support is on Vonage's roadmap, and we'll update this guidance when it becomes available.

No number registration, no number downtime, no loss of conversation history.

Tip: Do not remove your previous BSP before completing the Vonage ESU flow — if the number has live production traffic, removing the other partner first may cause downtime. Once Vonage is confirmed working, you can remove the previous BSP from your Messaging Account and WhatsApp Account if you no longer need them for this number. See STEP 10 of this guide below on how to remove the integration with BSP.

Steps to Share Your Existing WhatsApp Number with Vonage via Embedded sign-up flow:

These steps are for numbers already connected to another BSP. The Embedded Sign-Up (ESU) flow handles the WAAC sharing automatically — your number stays in place, and your existing BSP setup is not affected.

Important: Do not deregister or disconnect the number from your existing BSP before starting. Disconnecting the number does not free it up — the WAAC that owns the number must remain active and be shared with Vonage instead.

Step 1: Log in to the Vonage Dashboard and Launch Embedded Sign-Up

Log in to your Vonage Dashboard and navigate to Messages > External Accounts > Set up my WhatsApp Business Account to launch the Embedded Sign-Up flow.

Follow Steps 1–4 of the Getting Started with Vonage's WhatsApp Business API: New V4 Embedded Sign-Up flow guide to complete the initial setup, then continue with Step 2 below.

Step 2: Select Your Existing Business Phone Number

Select the phone number that is currently registered with your other BSP.

Your existing phone number — already registered with your other BSP — should appear in the dropdown. Select it from the list, then click Next. No verification is required as the number is already registered.

Step 3: Meta Pre-Selects Your Existing WhatsApp Account (WAAC) — Confirm Sharing

Because the number is already associated with a WAAC, Meta will automatically pre-select both the Business Portfolio and the WhatsApp Account (WAAC) — you do not need to select them manually.

You will see an important warning on this screen, as shown below:

Tick the checkbox "I have confirmed that all integrations on this number support conversation routing" and click Next.

Note: A new Messaging Account (PMA) will be created for Vonage under your existing WAAC. Your number and existing BSP setup are not affected.

Step 4: Enter Your WhatsApp Business Display Name

You will be prompted to enter a WhatsApp Business display name for your number.

Enter the display name you want to use for your WhatsApp number. Ensure your name follows WhatsApp's naming guidelines — Meta will validate it during this step.

Note: The display name will be reviewed by Meta after onboarding. You do not need to have it fully approved before proceeding. Click Next to continue.

Step 5: Review and Confirm Permissions

This screen provides a summary of the permissions you are granting to Vonage's app — covering access to your WhatsApp Account, Messaging Account, and associated assets. Review and click Confirm to proceed.

Step 6: Success Screen & Return to Vonage Set-Up

Once the flow is complete, Meta will display a success screen confirming the assets that have been created.

Back in the Vonage Dashboard, a "Next Steps" modal will appear (Step 1 of 2), confirming your WhatsApp number may now be used with some Limitations as shown below.

Step 7: Associate Number to a Vonage API Key

This is Step 2 of 2 in the Vonage flow — "Get your WhatsApp number Live with Vonage".

Your selected phone number is shown at the top. Select the Vonage API key you want your WhatsApp message traffic to go to.

We recommend using a separate sub API key for your WhatsApp traffic, for easier reporting and maintenance. You can create a new sub API key from the Vonage Dashboard if you don't have one already.

Once you have selected your API key, click "Get my WhatsApp number Live".

Step 8: Vonage Provisioning

Once you click "Get my WhatsApp number Live", Vonage will provision the WhatsApp phone number with your selected API key. This usually takes a few seconds, but may take up to a couple of minutes. Do not close this window whilst the provisioning is taking place.

Step 09: Integration with Vonage's API

To start sending and receiving messages via the Vonage Messages API, you need to link your WhatsApp number (External Account) to a Vonage Application.

Navigate to External Accounts in your Vonage Dashboard. You will see your newly provisioned WhatsApp number listed. Under the Application usage column, click "Link to an application".

Clicking "Link to an application" will take you to your Vonage Applications. Select the application you want to link your WhatsApp number to.

Once inside the application:

1. Navigate to the "External accounts" section within the application settings

2. Link your WhatsApp number to the application from there

Once linked, you can start sending and receiving WhatsApp messages via the Messages API

Refer to the Messages API code snippets to send a WhatsApp text message using the Messages API.

Step 10: Remove Previous BSP Access and Configure Vonage as Primary Responder

Important: Since Vonage does not currently support Thread Control, having the previous BSP still active as a partner — even after updating Conversation Routing — can result in inbound messages not being routed to Vonage. You must remove the previous BSP from both the Messaging Account and the WhatsApp Account to ensure incoming messages reach Vonage reliably. 

Thread Control support is on Vonage's roadmap, and this note will be updated when it becomes available.

Note: Sharing your WhatsApp Account (WAAC) with Vonage does not automatically remove your previous BSP or reroute inbound messages. Both steps below are required to fully transition to Vonage.

Part A: Remove the Previous BSP as a Partner

You must remove the previous BSP from both accounts in Meta Business Suite — the Messaging Account first, then the WhatsApp Account:

1. Go to Meta Business Suite and navigate to Settings > Accounts > Messaging Accounts

2. Select your Messaging Account → go to Partners → find the previous BSP's app → click Manage → Remove access

3. Navigate to Settings > Accounts > WhatsApp Accounts

4. Select your WhatsApp Account (WAAC) → go to Partners → find the previous BSP's app → click Manage → Remove access

Part B: Configure Vonage as Primary Responder in Conversation Routing

When a WhatsApp phone number is used by more than one BSP, Meta activates Conversation Routing — this manages which integration can view and respond to each conversation. Conversation Routing becomes active when two conditions are met: the account has more than one responder, and a routing configuration is in place.

A thread is a conversation between your business and a WhatsApp user on a specific phone number. Conversation Routing manages thread ownership — which responder (BSP) is responsible for a given thread at any point in time.

Note: Since Vonage does not currently support Thread Control (the ability to transfer, release, or take ownership of a thread), it is important to configure Vonage as the primary responder for all conversation types so that inbound messages are reliably delivered to Vonage. See Meta's Conversation Routing guide for full background.

Important: Even after removing the previous BSP, Meta does not automatically reroute inbound messages. You must update Conversation Routing to ensure incoming messages reach Vonage.

1. Go to Meta Business Suite and navigate to Settings > Accounts > WhatsApp Accounts

2. Select the WhatsApp Account (WAAC) associated with your phone number

3. Click the Conversation routing tab; here you can manage who can access and respond to your business conversations

4. Click Manage under Message routing

  5. Assign Vonage Communication APIs & Conversational Commerce Platform to each conversation type as shown below and click Apply

Important: Select Vonage in every row — Vonage does not currently support standby mode, so any conversation type not assigned to Vonage will not reach you.

  6. Click Apply

Once updated, inbound messages to your WhatsApp number will be routed to Vonage and delivered to your configured Webhook endpoint.

Note: If you remove the previous BSP (Part A), the routing configuration is deleted automatically when fewer than two responders remain on the account. This disables Conversation Routing and returns delivery to default behaviour — every connected responder receives all messages. In practice, once the previous BSP is removed and Vonage is the only responder, all inbound messages will be delivered directly to Vonage without requiring a routing configuration.

What you can do once Vonage is connected:

• Template messages — not restricted by thread ownership. You can send template (business-initiated) messages to customers as soon as your number is connected to Vonage, regardless of Conversation Routing configuration.

• Service messages (replies within a 24-hour customer-initiated window) — once Conversation Routing is configured to Vonage and the previous BSP has been removed, you can respond to customer messages with service messages through Vonage.

Still having issues after removing the other BSP? If you are still unable to send service messages or receive inbound messages after completing all steps, please contact Vonage Support for assistance.

Templates

Templates belong to the Messaging Account (PMA), not the phone number. When Vonage creates a new Messaging Account under your WAAC, it starts with no templates. You will need to recreate your templates in Vonage.

Part C: Delete the Previous BSP's Messaging Account (Optional)

If you want to fully remove the previous BSP's Messaging Account (PMA), you can delete it from Meta Business Suite. However, if there is an outstanding balance from paid messages, you will see the following error:

"Your account has an outstanding balance. You will be able to delete it once you have paid it."

You will be able to delete the Messaging Account once:

• The billing cycle has passed, and

• The previous BSP has cleared the outstanding balance

Until then, the Messaging Account will remain but will no longer have access to your WhatsApp Account once Part A is complete.

Understanding What Changes and What Stays the Same When a WhatsApp Number is Shared Between BSPs

When Vonage is added as a partner on your number, some things are shared across all BSPs and some are isolated per partner. Here is what to expect:

Step 11: Next Steps to Get the Most from WhatsApp

If/when required, you can start the Facebook Business Verification process.

Once Business Verification is approved, or once your messaging tier reaches 2,000 messages in a rolling 24-hour period, the display name review is triggered automatically for all numbers within the Messaging Account (PMA).

For Tech Providers: Migrating a Customer from Another Multi-Partner Solution to Vonage

If you are a Tech Provider migrating a customer's WhatsApp number from one Multi-Partner Solution to Vonage, the process involves instructing your customer to unshare/remove access (not delete) to their accounts from the source solution, then completing Embedded Sign-Up to share with Vonage.

Important: The customer must unshare their accounts — not delete them. Deleting the Messaging Account or WhatsApp Account will result in loss of data and phone number registration.

Steps

Step 1: Instruct the end client customer to unshare their accounts from the previous BSP

Ask the customer to:

1. Go to Meta Business Suite > Settings > Accounts > Messaging Accounts

2. Select the Messaging Account associated with the phone number

3. Unshare the previous BSP's app from the Messaging Account

4. Navigate to Settings > Accounts > WhatsApp Accounts

5. Select the WhatsApp Account (WAAC) associated with the phone number

6. Unshare the previous BSP's app from the WhatsApp Account

Note: Unshare in this order — Messaging Account first, then WhatsApp Account.

Step 2: Instruct the customer to complete Embedded Sign-Up with Vonage

Once both accounts have been unshared from the previous BSP, Direct your client to complete the Vonage Embedded Sign-Up flow. Follow the steps in the Hosted Embedded Sign-Up guide (recommended) or your own integrated Embedded Sign-Up flow.

When the customer enters their existing phone number in the ESU flow, Meta will automatically pre-select the existing WAAC, and a new Messaging Account (PMA) will be created for Vonage.

Step 3: Update Conversation Routing

After the customer completes ESU, ensure Conversation Routing is updated to Vonage in Meta Business Suite — see Step 10(Part B) of this guide.

Step 4: Migrate Templates Using the Meta's Template Migration API.

Important: The Template Migration API is not currently supported by Vonage. Until support is available, all templates must be recreated manually in the new Vonage Messaging Account (PMA). The rules below apply once the Template Migration API becomes available — this article will be updated when Vonage adds support.

Templates are not duplicated automatically in this flow. You must duplicate them yourself using the Template Migration API. Before calling the API, you will need:

• The source Messaging Account ID (the account being migrated from)

• The destination Messaging Account ID (the new one created by Vonage ESU)

• A valid access token with the required permissions

For full reference, see Meta's guide on migrating customers between solutions via Embedded Sign-Up.

Number Already Registered with Vonage

If your phone number is already tied to an existing Vonage account (i.e., a Vonage Messaging Account/PMA has already been created for it), attempting to go through the Embedded Sign-Up flow again will result in an error — Vonage's backend will detect the number is already registered under a different Vonage account.

This can happen if:

• The number was previously onboarded to Vonage under a different API key or account

• A previous ESU attempt partially completed and left the number registered in Vonage's system

• The number belongs to another Vonage customer

What to do: You will need to contact the Vonage Support Team to investigate and resolve the conflict before the number can be onboarded to your Vonage account.

Moving a Number Between WhatsApp Accounts (WAACs)(Previously Moving a number from one WABA to another within Vonage)

Migrating a phone number from one WhatsApp Account (previously WABA) to another within Vonage is no longer supported under Meta's new account model. Instead, you can link and unlink numbers between WhatsApp Account hierarchies within the same Business Portfolio using Meta Business Suite — the number stays connected and keeps its conversations.

How to Link / Unlink a Number

In Meta Business Suite, go to Settings > Accounts > WhatsApp Accounts, select the primary WhatsApp Account, and open the Linked WhatsApp accounts tab:

• Unlink a number — select Unlink number on a linked number to move it into its own WhatsApp Account hierarchy, or directly into another hierarchy in the same Business Portfolio.

• Link a number — select Link WhatsApp account > Existing WhatsApp account to add a number the business already owns to this hierarchy.

Below points to be noted:

• Both hierarchies must belong to the same Business Portfolio — a number cannot be moved between different Business Portfolios.

• Partners with access to a hierarchy have access to every number in it — moving a number changes which partners can use it.

• You need permission to manage phone numbers on every hierarchy involved, and the number must be connected (i.e not under unverified, pending, or restricted/banned statuses)

• As per Meta, linking and unlinking are rolling out gradually and may not be available for every business yet.

Frequently Asked Questions

How do I share my phone number with Vonage? You do not share the phone number directly — you share the WhatsApp Account (WAAC) that owns it. To do this, complete the Vonage Embedded Sign-Up flow: enter your existing phone number when prompted, and the corresponding WAAC will be automatically pre-selected. Vonage will be added as an additional partner with its own Messaging Account (PMA) created under your WAAC. See the steps above under Steps to Share Your Existing WhatsApp Number with Vonage in this guide above

Will I lose my conversation history? No — conversations are tied to the phone number, not the Messaging Account or BSP. Your conversation history is retained.

Can I free up my number by disconnecting it from my current BSP first? No — disconnecting a number from its current account does not make it available. The number must remain in its current WAAC, which is then shared with Vonage.

Do I need to re-verify my business with Meta? No — Business Verification is tied to your Meta Business Portfolio, which already exists. You do not need to re-verify.

Will my existing templates still work with my previous BSP? Yes — your existing Messaging Account (PMA) and its templates remain unaffected. Only a new Messaging Account is created for Vonage. Note that templates do not carry over to Vonage's Messaging Account — you will need to recreate them.

Can I use the same number with both my previous BSP and Vonage at the same time? Technically yes at Meta's level — sharing is additive and both BSPs can have separate Messaging Accounts. However, Vonage does not currently support Thread Control, which means having two active BSPs can cause inbound message routing conflicts. It is recommended to remove the previous BSP once Vonage is confirmed working.

Why am I not receiving inbound messages after sharing my number with Vonage? Sharing your WhatsApp number (WAAC) with Vonage does not automatically reroute incoming messages to Vonage. Meta continues to send inbound messages to your previous primary BSP until you update your Conversation Routing settings and remove the previous BSP. See Step 10 for full instructions.

What if I want to use only Vonage and remove my previous BSP? You can remove your previous BSP at any time — it is not a prerequisite for onboarding Vonage. Once you have completed the Embedded Sign-Up flow and confirmed Vonage is working correctly, follow Part A of Step 10 to remove the previous BSP from both the Messaging Account and the WhatsApp Account.

Get Help

If you have any questions or run into any issues, please contact our Support Team for assistance.

Additional Information

Getting Started with Vonage's WhatsApp Business API: New V4 Embedded Sign-Up flow