Moving away from Vonage - WhatsApp (WhatsApp Phone Number Migration is not supported anymore)

Objective

This guide explains how to offboard a WhatsApp Business number from Vonage under Meta's new WhatsApp account model. It covers three scenarios:

• Moving to another BSP

• Offboarding from Vonage without switching to a new BSP

• Deleting a number from the WhatsApp Business API to use on personal WhatsApp

Applies To

• Messages API
• WhatsApp

About the New WhatsApp Account Model

Under Meta's new account model, a WhatsApp Business number sits in a WhatsApp Account (WAAC) which sits under your Meta Business Portfolio. When you onboard with Vonage, a separate Messaging Account (PMA) is created for Vonage under your WAAC — this is where your templates and line of credit (for billing) with Vonage live.

Sharing is additive. A WhatsApp Account can be shared with more than one BSP or partner at the same time. Moving to a new BSP does not require migrating or transferring the number — the client simply shares their existing WAAC with the new BSP in addition to Vonage. The number stays in place, and conversations are uninterrupted. Whether the client keeps Vonage on the number or removes them later is entirely their decision, and neither is a prerequisite for onboarding with a new BSP.

Note: If your account is still on the old WhatsApp account model (you only see WhatsApp Accounts in Meta Business Suite, not Messaging Accounts), please contact Vonage Support before proceeding.

Scenario 1: Moving to Another BSP

If you or your client want to switch from Vonage to another BSP, follow this order to ensure a smooth transition without any downtime:

Important: Do not delete the Vonage Messaging Account until the new BSP is fully set up and confirmed working — deleting it prematurely will cause downtime if the number has live production traffic.

Step 1: Onboard with the new BSP

Complete the new BSP's Embedded Sign-Up (ESU) flow to share your WhatsApp Account with them. This creates a new Messaging Account for the new BSP under your existing WAAC. Your number remains active with Vonage throughout this process — there is no disruption.

Step 2: Verify the new BSP onboarding is successful

Before proceeding, confirm the following in Meta Business Suite > Settings > Accounts:

• Under Messaging Accounts — a new Messaging Account for the new BSP is visible and shows the number as connected

• Under WhatsApp Accounts — the new BSP appears as a partner on the WAAC

• The new BSP confirms on their end that the number is active and ready to use

Once confirmed, proceed to update Conversation Routing as per your (end clients') requirements. For example, if you want the new BSP to be the primary responder, this can be configured accordingly. For more details, refer to Meta's Conversation Routing documentation.

Step 3: Configure the New BSP 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 BSP can view and respond to each conversation. You must update this to ensure inbound messages are delivered to the new BSP.

Important: Even after completing the new BSP's ESU flow, Meta does not automatically reroute inbound messages. You must update Conversation Routing to ensure incoming messages reach the new BSP.

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

4. Click Manage under Message Routing

5. Assign the new BSP to each conversation type and click Apply, as shown in the example when switching to Vonage; instead of Vonage, you can select the new BSP.

Also ensure the new BSP's webhook subscription is in place; your new BSP will be able to confirm this for you.

What you can do once the new BSP is connected:

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

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

  Note: If you intend to keep Vonage active alongside your new BSP, check with your new BSP whether they support Thread Control before doing so.

Step 4: Confirm the new BSP is working

Verify that the number is connected and live with the new BSP. Test sending and receiving messages before removing Vonage as a partner.

Step 5: Unshare Vonage from your accounts

Once the new BSP is fully set up and confirmed working, go to Meta Business Suite > Settings > Accounts and:

1. Under Messaging Accounts → Partners →find the Vonage app →  Click Manage → Remove access

2. Under WhatsApp Accounts → Partners → find the Vonage app → Click Manage → Remove access

Note — Multi-Partner Solution: If you were using a Multi-Partner Solution with more than one Partner active on your number, while in Partners, remove all Partner apps related to the previous Multi-Partner Solution(not the new Partner APP) from both the Messaging Account and the WhatsApp Account in the same step.

Step 6: Contact Vonage Support to Revoke Credit Line and Remove Number from Vonage Backend (Optional)

Once the unshare is complete, please contact Vonage Support with the following details so we can revoke the credit line and remove the number from Vonage's backend:

• Messaging Account ID (previously known as WABA ID)

• Business Portfolio ID

• WhatsApp Phone Number

• Vonage API Key

Until the number is removed from Vonage's backend, it will continue to appear under External Accounts in your Vonage Dashboard.

Step 7: Delete the Vonage Messaging Account (Optional)

If you want to fully remove Vonage's Messaging Account (PMA):

• Go to Meta Business Suite > Settings > Accounts > Messaging Accounts

• Select the Vonage Messaging Account

• Click the three dots (⋯) in the top right-hand corner

• Click Remove from business portfolio as shown in the screenshot below

• If you see the error "Your account has an outstanding balance. You will be able to delete it once you have paid it." — wait for the monthly billing cycle to pass and for Vonage to clear the balance before attempting deletion again. This does not affect the usage of your number on your new BSP platform, as the new BSP has its own separate Messaging Account with its own credit line.

Templates

Vonage's Messaging Account and its template library will be removed when the account is deleted. If the new BSP needs the same templates, they must be recreated manually in the new BSP's Messaging Account.

Scenario 2: Offboarding from Vonage Only (No New BSP)

If you simply want to stop using Vonage and do not plan to use another BSP, follow these steps:

Step 1: Unshare Vonage from your accounts

Go to Meta Business Suite > Settings > Accounts and:

1. Under Messaging Accounts → Partners →find the Vonage app →  Click Manage → Remove access

2. Under WhatsApp Accounts → Partners → find the Vonage app → Click Manage → Remove access

Step 2: Contact Vonage Support to Revoke Credit Line and Remove Number from Vonage Backend

Once the unshare is complete, please contact Vonage Support with the following details so we can revoke the credit line and remove the number from Vonage's backend:

• Messaging Account ID (previously known as WABA ID)

• Business Portfolio ID

• WhatsApp Phone Number

• Vonage API Key

Until the number is removed from Vonage's backend, it will continue to appear under External Accounts in your Vonage Dashboard.

Step 3: Delete the Vonage Messaging Account (Optional)

• Go to Meta Business Suite > Settings > Accounts > Messaging Accounts

• Select the Vonage Messaging Account

• Click the three dots (⋯) in the top right-hand corner

• Click Remove from business portfolio as shown in the screenshot below

• If you see the error "Your account has an outstanding balance. You will be able to delete it once you have paid it." — wait for the monthly billing cycle to pass and for Vonage to clear the balance before attempting deletion again.

Scenario 3: Deleting a Number from WhatsApp Business API to use on Personal WhatsApp

If you want to stop using a phone number on the WhatsApp Business API and use it on a personal WhatsApp account instead, you need to delete it from WhatsApp Manager:

1. Go to WhatsApp Manager

2. Under Account Tools, navigate to Phone Numbers

3. Click the trash icon on the right side of the number you want to delete

Note: If the number was used to send paid messages within the last 30 days, you will not be able to delete it immediately. You will need to wait until the 30-day period has passed, or until your BSP's payment to Meta has been processed during the next billing cycle.

Frequently Asked Questions

What is the process to share an existing WhatsApp number from another BSP to Vonage? 

Phone number migration between BSPs is not supported under Meta's new account model. Instead, your existing WhatsApp Account (WAAC) is shared with Vonage — the number stays in place and conversations are uninterrupted. For the full step-by-step process, refer to the Connecting an Existing WhatsApp Business Number to Vonage via Embedded Sign-Up guide.

Does the customer's Meta Business Portfolio need to be verified before connecting to a new BSP? 

No — Business Verification is tied to the Meta Business Portfolio, which already exists and remains in place when you switch BSPs. The new BSP does not require re-verification before onboarding. However, if the portfolio is unverified, the new BSP account will start with the same restrictions (2 phone numbers, 250 business-initiated conversations per 24 hours) until verification is completed.

Does the WhatsApp display name need to be approved before switching to a new BSP? 

No — the display name is tied to the WhatsApp Account (WAAC), not the Messaging Account (PMA). It remains in place when you switch BSPs. The new BSP does not require display name re-approval before onboarding. However, if the display name was not yet approved with Vonage, it will still be pending approval under the new BSP.

What exactly needs to be done to fully remove Vonage's access? 

To completely offboard from Vonage without downtime, follow this order:

1. Complete ESU with the new BSP first — share the WAAC with the new BSP and confirm the number is working before removing Vonage

2. Update Conversation Routing — assign the new BSP as primary responder and ensure webhook subscription is in place

3. Remove Vonage from the Messaging Account — Meta Business Suite > Settings > Accounts > Messaging Accounts > Partners > find Vonage > Remove access

4. Remove Vonage from the WhatsApp Account — Meta Business Suite > Settings > Accounts > WhatsApp Accounts > Partners > find Vonage > Remove access

5. Optionally delete the Vonage Messaging Account — once the monthly billing cycle has passed and any outstanding balance is cleared

Note: Do not remove Vonage's access before the new BSP is fully set up and confirmed working — doing so on a live number may cause downtime.

What are the prerequisites before connecting an existing WhatsApp number from another BSP to Vonage?

• Admin access to the Meta Business Portfolio

• The number must be on Meta's new account model (both WhatsApp Accounts and Messaging Accounts visible in Meta Business Suite)

• The number must be active and connected to a WAAC under your Meta Business Portfolio

• Do not disconnect or deregister the number from the current BSP before starting — sharing is additive and the number can be connected to multiple BSPs simultaneously

• A Vonage account and access to the Vonage Dashboard

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

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