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

Objective

Did you know you can onboard and send WhatsApp messages in as little as 10 minutes?

Vonage's Embedded Sign-Up is the fastest and most efficient way to get started with WhatsApp for Business.

Applies To

• WhatsApp Embedded SignUp

What is Embedded Sign-Up?

It's a self-service onboarding tool, embedded in Vonage's Customer Dashboard, allowing you to onboard an existing or new WhatsApp business account or phone number onto Meta.

New Account Model (Meta GA Launch)

Meta has updated the WhatsApp Business Account structure. What was previously a single WABA (WhatsApp Business Account) is now split into two distinct account types:

• WhatsApp Account (WAAC): Owns the phone number and similar assets. This can be thought of as a set of user-facing brand identifiers of the business. A phone number can be shared across multiple partners and integrations.
• Messaging Account (PMA): Owns templates, billing, currency, timezone, etc. Each BSP integration (e.g. Vonage, Twilio, 360dialog) gets its own isolated Messaging Account. The Messaging Account ID is the equivalent of the WABA ID — use this for all API calls and template management. For existing migrated customers, this is the same value as your previous WABA ID.

Most Vonage customers have already been migrated automatically as part of Meta's Phase 1 GA launch. No action is required for existing accounts that have been migrated.

Creating your own WhatsApp Account means it's owned and managed by you and your business, giving you more control and flexibility.

Illustrative Pics from Meta docs

Who is this guide for?

This flow is for direct customers only — businesses that will be using WhatsApp for their own business use.

If you are creating a WhatsApp Account on behalf of another business (for example, as a Partner or Billing Agent), this flow does not apply to you. You must first become a Vonage partner by reaching out here.

Once you are a Vonage partner, you must enrol as a tech provider and complete Meta's Tech Provider Enrollment program. Please refer to the Tech Provider Enrollment guide.

Once enrolled as a Tech Provider, you have two options for onboarding your end clients' WhatsApp Business Accounts:

Prerequisites for using Embedded Sign-Up

• You must have access to your business Vonage Communications API Account via the Vonage Dashboard

• You must have an active personal Facebook Account

• You must have access to your business's Facebook Business Manager Account. If you don't have one, you can create one via Embedded Sign Up (see below).

• You'll need the phone number you want to use for WhatsApp. This can be either a Vonage LVN or your own number. In either case, the phone number must meet the following requirements:

  • Must accept VOICE calls or SMS (for Contact Centre numbers, the IVR system must be able to be disabled or intercepted to complete the 2FA)

  • Not a short code or toll-free number

  • Business phone numbers can only be registered for use with the Cloud API

If your number is already in use with WhatsApp:

• Already with another BSP (via WAAC): If your number is already tied to a WhatsApp Account (WAAC) shared with another BSP, you can still use it in this Embedded Sign Up flow — Vonage will be added as an additional partner with its own Messaging Account, and your existing BSP setup is not affected.

• Personal WhatsApp App: The number must be deleted from the personal app before it can be registered via Embedded Sign Up.(Refer to Meta Documentation)

• WhatsApp Business App: Co-existence (using the same number on both the WhatsApp Business App and the Cloud API simultaneously) is not yet supported by Vonage — this is on our roadmap, and this article will be updated once it becomes available. Until then:

  • You must delete the number from the WhatsApp Business App first.

  • The number will then need to be registered as a new number via Embedded Sign Up.

  • Note: Chat history from the WhatsApp Business App will not be retained after migration to the Cloud API.

    For reference, Meta does support onboarding Business App users via a customised Embedded Sign Up flow — see Meta's guide on onboarding WhatsApp Business App users for background. Vonage will update this process once co-existence support is available.

Phone Number Migration & Moving Numbers: Under Meta's new account model, phone number migration between Solution Partners is no longer supported. If you are moving to Vonage from another BSP, or want to move numbers within your business portfolio, see the Phone Number Migration section below.

Procedure

Onboarding Action Items

To use Embedded Sign Up, follow the instructions below.

1. Access Embedded Sign Up

Navigate to the External Accounts section in the Vonage Dashboard.

Click on "Set up my WhatsApp Business Account".

2. Continue To Facebook Hosted Set-Up

You'll then be presented with an introductory screen explaining the requirements and important information about Embedded Sign Up.

Ensure you have read and understood this information before you click through to the Facebook-hosted screens.

3. Log in with Facebook

In order to use Embedded Sign Up, you will need to have an active Facebook account. The first thing you'll need to do is log in with this Facebook account. If you do not have a Facebook account, you will need to create one.

4. Confirm Sharing with Vonage

You will see an introductory screen — "Seamlessly connect your account to Vonage Communication APIs & Conversational Commerce Platform" — which explains that this onboarding process will register and connect your business account to Vonage as your partner.

Review and agree to the Meta terms shown on screen before continuing.

Vonage acts as your WhatsApp Business Solution Provider (BSP) and will manage your integration through its own dedicated Messaging Account (PMA) — keeping your billing and templates isolated from any other BSP you may use. 

Click Continue to proceed.

5. Enter & Verify your WhatsApp Phone Number

The phone number is the first piece of information collected in the Facebook-hosted flow.

Enter the phone number you will be using for WhatsApp. The dropdown also lets you select an existing business phone number already associated with your account (each shown with its eligibility status), or choose to use a display name with a virtual number instead.

Note: Phone number limit: New Business Portfolios are initially capped at 2 registered business phone numbers in total across the portfolio. This cap increases automatically to 20 if your business becomes verified by Meta or you reach a messaging tier of 2,000.

Note: If your number is currently registered with another Solution Partner (BSP) and you want to share it with Vonage, you can enter or select that same number here. Vonage will be added as an additional partner with its own Messaging Account (PMA) created under your existing WhatsApp Account (WAAC) — your number stays in place, and your existing BSP setup is not affected.

If you would like to purchase a phone number on the Vonage API Dashboard, you can do this through the Buy Numbers section (additional documentation: How to purchase a number for your Virtual Agent?).

If you are verifying a Vonage LVN, read the relevant section below before selecting your verification method and clicking Send Code:

• SMS: The code will be delivered to your LVN. To retrieve it, open SMS Logs in a new browser tab (do not navigate away from the Embedded Sign Up flow or it will close), set Phone Number to your LVN under 'To' Number, and set Direction to Inbound — the OTP will appear there.

• Voice Call: The call will come in to your LVN. You must set up call forwarding to a personal phone number before clicking Send Code, otherwise the OTP call will not reach you.

Setting up Voice Call forwarding for a Vonage LVN as shown in the screenshot:

1. Open Your Numbers in the Vonage Dashboard in a new browser tab

2. Click Edit on the LVN you are using

3. Under Voice, set Forward to → Phone and enter your personal phone number

4. Click Save

Note: Once forwarding is configured, return to the Embedded Sign Up flow and proceed. Once the OTP has been received and verified, you can revert the forwarding setting if needed.

Meta will send you a verification code to confirm you own this number. Select whether you would prefer to receive the code via SMS or Voice Call, then click "Send Code".

Once you've received the code, enter it on the next screen.

• If you haven't received the code, wait the allocated time until you can retry.

• If you are still having trouble, ensure that your phone number is able to accept Voice Calls or SMS. The code can sometimes come from a US (+1) phone number, so ensure your phone number accepts international calls.

• If you need to change the phone number, follow the instructions on the screen to "provide a new one".

6. Select or Create your Business Assets

This screen lets you select existing business assets — your Meta Business Portfolio (formerly Facebook Business Manager) and WhatsApp Account (WAAC) — to associate with your phone number. You can also create new assets if you have not reached your portfolio limit. Note that Meta allows each user to personally create a maximum of 2 Business Portfolios. There is no limit on the number of portfolios a user can belong to — only on how many they can personally create. If you have reached this limit, see Unable to Create a New Meta Business Portfolio — Creation Limit Reached for options.

Meta Business Portfolio (formerly Facebook Business Manager):

Select the Business Portfolio of the business you are creating a WhatsApp Account for.

If you do not have one, you can create a new one. You'll need to enter:

• Business name

• Business email

• Category (type of business)

• Country

• Website (optional, but recommended — entering your website helps avoid issues during profile creation)

Click Next to proceed.

Important: If you create a new Business Portfolio, you will also need to create a new WhatsApp Account (WAAC) — you will not be able to select an existing one, as any existing WAACs you may have are tied to your other Business Portfolio(s), not the new one. Only if you select an existing Business Portfolio will you be able to choose a WhatsApp Account (WAAC) with a phone number already associated with it.

WhatsApp Account (WAAC):

Under Meta's new account model, onboarding via Embedded Sign Up will create both a WhatsApp Account (WAAC) and a Messaging Account (PMA) for your business.

Depending on your selection, here is what gets created:

• If the phone number you entered in Step 5 is already associated with another BSP, the corresponding WhatsApp Account (WAAC) will be automatically pre-selected here — you do not need to select it manually. Only a new Messaging Account (PMA) will be created for Vonage under that existing WAAC. Your number and existing BSP setup are not affected.

• If you do not have a WAAC yet, or are selecting an existing portfolio and creating a new WhatsApp Account, a new WAAC and a new Messaging Account (PMA) will be created.

7. Review 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 confirm to proceed.

8. Success Screen & Return to Vonage Set Up

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

• Business — your Business Portfolio

• WhatsApp account — your WhatsApp Account (WAAC)

• Messaging account — named [Your Business] - Vonage Communication APIs & Conversational Commerce Platform, confirming it was created via the Vonage ESU flow

Note: If you click Messaging Account on the success screen, it will take you to your Business Portfolio where you can find your Messaging Account ID — this is your WABA ID, and the ID you should use for all API calls and template operations. For existing migrated customers, this is the same value as your previous WABA ID, just renamed.

Click "Continue to feature setup". This will take you to the WhatsApp Manager Setup Guidance page, which shows a checklist of tasks to fully unlock WhatsApp Business features.

Note: These other tasks related to Business verification etc that you see in WhatsApp Manager page are not mandatory at this stage. You do not need to complete them now. Close or minimise this tab and navigate back to the Vonage Dashboard to continue with the flow and get your WhatsApp number live with Vonage.

Back in the Vonage Dashboard, a "Next Steps" modal will appear (Step 1 of 2), confirming your WhatsApp number may now be used but may have some limitations. To get unrestricted use of your number, you will eventually need to:

• Verify your business with Meta

• Have your display name approved by Meta

• Meet Meta's Commerce Policy requirements

These are covered in Step 12 of this guide. For now, click "Next" to proceed.

9. 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".

10. 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.

Once successfully completed, you will see "Your number is live with Vonage" with a green checkmark. The phone number will now also appear on your Vonage Dashboard under External Accounts.

The above next steps do not need to be completed before you can start using the number. However, to immediately start sending and receiving messages via the Vonage Messages API, you must link your number (External Account) to a Vonage Application. See Step 11 below.

Business Verification with Meta (for messaging limit increases and display name approval, OBA access, etc.) can be completed later — see Step12

Click "Go to dashboard" to return to your Vonage Dashboard.

11. 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 sample code snippet to send a WhatsApp Text message using the Messages API 

You can start messaging customers without having to complete Business Verification or Display Name reviews.

With the above steps complete, you will immediately be able to:

• Respond to unlimited customer-initiated conversations (24-hour messaging windows)

• Send business-initiated conversations to 250 unique customers in a rolling 24-hour period

• Register up to 2 phone numbers

There is no time limit to this stage. Businesses can remain at this "unverified" status as long as required, only completing Business Verification to scale or gain Official Business Account status.

12. Next Steps to Get the Most from WhatsApp

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

Once Business Verification is approved, the display name review is triggered automatically for all numbers within the Messaging Account (PMA).

With your business verified and display name approved, you can:

• Scale your business-initiated conversations following Meta's standard messaging limit tiers

• Add more than 2 phone numbers to your WhatsApp Account

• Request Official Business Account (Green Label) status

Quality Rating

Maintain a high quality rating on your phone number and template quality to scale your messaging limits over time.

Phone Number Migration

Migrating from Another Solution Partner

Migrating a business phone number from one Solution Partner (BSP) to another is not supported in Meta's new account model.

Instead, a client who wants to work with Vonage shares their existing WhatsApp Account (WAAC) with Vonage. The number does not move, conversations are uninterrupted, and there is no migration to perform. A new Messaging Account (PMA) is then created under the existing WAAC, linked to Vonage for billing and template management.

Key points:

• Sharing is additive. Whether your client keeps their previous BSP on the number or removes them later is entirely their decision — neither is a prerequisite for onboarding Vonage.

• Moving between Multi-Partner Solutions is unaffected. When a customer shares their WAAC with a new BSP, any existing Multi-Partner Solution relationships on that number are not disturbed by the sharing action itself.

Get Help

If you get stuck at any point during the process, please reach out to our Support team via our Support Channel.

Additional Information

Understanding WhatsApp Messaging

Meta Updates to WhatsApp Accounts

Meta's Template Quality Rating