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 "Full Control" or Admin permissions in the Business Portfolio in which a WABA or WhatsApp number is to be onboarded
• 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 Embedded Sign-up flow experience hosted by Vonage through which WhatsApp Business Account (WABA) or WhatsApp number onboarding registration can be completed
4. The customer completes the onboarding process using the embedded sign-up flow

Generating an 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.

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 main 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 (Max 3 days; if omitted, the default validity of 86400 seconds, or one day, is used).

Example Request Body

{
  "solution_id": "123456789111213",
  "api_key": "abc123", // Optional
  "ttl": 3600 // Optional
}

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.

{
  "id": "3amb0119-0196-42d1-8fb5-55a98s133546",
  "url": "https://tools.vonage.com/wa/partners/onboard?token=fhdhhdJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3MjU5Njc1OTYsImp0aSI6ImQ1MmJhNmFjLWYxZjktNDdmNC05MTR_cFT1bVfkDhP-wgpKZibSbUoh9z-9KGD-wsmHxi0h7tTidpVhPNShfC5jmgiHtOQKXXv5NWb9OqoUraOMMpqCdNdXoN3ao-PeZX7axyYW_FQ6CeV9gDEPhAZ4urTi0uW4mCYGl3ULmA9Ps92r_wi2DJyRE_Kx2KahWtQd51yVpU6FfXgMb4odREEccDctT1Peo09wKgwBa1wsOkD7rrvkoQPqZ00VXcqOY1_LOO5tq4WJaKqtxX-U7VtDo9qyVUl8pdegZW6QWChQzGN4PkqXXLWcBlyrCtAYdhtWG8q6NM_6bARRjcGJlj0tQvE0PZ9AtafAQSPpOll5lcnUK8Ds"
}

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 in the following ways:

• Manually checking the status of a number
• Subscribing to updates about a number

Manually checking the status of a number

In order to manually check the status of a number you can visit the WhatsApp Manager interface of your WABA. An active number will show a Status of Connected.

Subscribing to updates about a number

You can subscribe to updates about the change in verification status of a number using WhatsApp Notification Subscriptions.

Subscriptions can be created for many different events; you can read more about these in the WhatsApp Notification Subscriptions Guide Document. For number status updates, you must create a subscription with the account_update subscription type in the whatsapp_subscribe_types, and also the vonage_number_onboarded subscription type in the vonage_subscribe_types.

The notification is triggered by a PARTNER_ADDED event and is sent to the webhook or Slack hook you specified when creating the subscription. The notification payload will include the waba_id, solution_id, and owner_business_id details.

The payload for a POST request to the https://api.nexmo.com/v2/whatsapp-manager/subscriptions endpoint would look something like the following:

{
  "type": "webhook",
  "label": "#dk-test",
  "whatsapp_subscribe_types": "account_update", // or can be left blank ""
  "vonage_subscribe_types": "vonage_number_onboarded",
  "webhook": {
      "url" : "https://eo34s4y0tl.m.pipedream.net"
  }
}

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.