WhatsApp Hosted Embedded Sign-up Flow for Tech Partners

WhatsApp Hosted Embedded Sign-up Flow is a white-labeled onboarding UI. It enables Vonage Partners to onboard their clients to WhatsApp Business Accounts without the need to create, configure or host their own Embedded Sign-up Flow.

Prerequisites

In order to leverage the embedded sign up solution, Vonage Partners must fulfil the following prerequisite requirements:

  • Register with Meta as a Tech Provider
  • Have a Meta App Live on the App Dashboard
  • Have Administrator permissions in the Business Portfolio
  • Have submitted a Solution Request to Vonage, had the request accepted, and been provided with a Solution ID

If you have questions about, or need support with, any of the prerequisites listed above, please contact your Vonage Account Manager.

Process Flow

The process flow for WhatsApp Hosted Embedded Sign-up is as follows:

  1. The Vonage Partner generates an embedded sign-up URL
  2. The Partner can share the URL with their customers (for example via email or SMS, or via embedding the URL on their own web page)
  3. The URL directs the customer to a white-labeled WhatsApp number onboarding page hosted by Vonage
  4. The customer completes the registration process within the embedded sign-up flow
  5. The WhatsApp Number is verified via an OTP sent to the number

Note: Registration or deregistration attempts for every WhatsApp number are limited (10 attempts per number per week).

Generating and Embedded Sign-up URL

An embedded sign-up URL can be generated by making an POST request to the Generate Hosted ES Flow URL endpoint of the Channel Manager API.

Note: the Channel Manager API is currently in Beta release status.

Authentication can be done via Basic Auth or Bearer Token (JWT) Auth.

The request body should contain a JSON object with, at minimum, a solution_id property, the value of which is the Solution ID provided by Vonage (see prerequisites).

The body can also contain an api_key property to identify the Vonage sub-account of the customer for whom the Partner wishes to create the URL (if this property is omitted, the API Key for the primary Vonage account is used).

A ttl property can also be specified to set the time limit on the validity of the generated URL (if omitted, the default validity of 86400 seconds, or one day, is used).

Example Request Body

Example Response Body

A successful response will return a HTTP Status Code of 200 and include a response body with a JSON object that contains the generated Embedded Sign-up URL, as well as a Trace ID for the request.

Checking the WhatsApp Phone Verification Number Status

As part of the WhatsApp Number registration process, a One-Time Password (OTP) will be sent to the number being registered in order to verify the number. Verification must be successfully completed prior to the number being used.

The number verification status can be checked via the Get a WhatsApp Business Account Number endpoint of the Channel Manager API. The value of the code_verification_status in the response body should be VERIFIED.

Note: Client administrators will also receive an email notification and a Meta Business Suite notification regarding onboarding status.

Linking a WhatsApp Number with a Vonage Application

In order for the WhatsApp number to be used to send messages via the Vonage Messages API, it needs to be linked to a Vonage Application.

This can either be done via the Vonage Dashboard or via the Link application to an account endpoint of the External Accounts API.

Notes for Partners

  • No separate enablement is required for a Vonage Partner/ Tech Provider to use Hosted Embedded Signup Flow. It can be accessed using the main api-key and associated credentials.
  • Only 'Shared' WhatsApp Business Accounts (WABAs) of clients can onboard new WhatsApp numbers via the Hosted Embedded Sign-up flow or any Embedded Sign-up flow. For OBO WABAs, manual onboarding has to be used. Please see the Meta Documentation for details about OBO and Shared WABAs.
  • Vonage Partners/Tech Providers should ensure that their client(s) using the Hosted Hosted Embedded Flow have filled and completed Business Details in their Business Portfolio Info section. If any required details, e.g user business email, are invalid, the onboarding process is likely to fail.
  • During WhatsApp number registration, the expected response time from the Meta API can be up to 120s.
  • Registration or deregistration attempts for every WhatsApp number are limited by Meta (10 attempts per number per week). After reaching this limit, the number will be blocked for registration.