This document explains how to offer your end clients pre-verified business phone numbers in the new Embedded Signup flow. Pre-verified business phone numbers are business phone numbers that have already been verified by you, eliminating the need for end clients to have to contact you for a one-time password.
Note that pre-verified business phone numbers are represented by WhatsApp Business Pre-Verified Phone Number objects, which are temporary. When an end client selects one of these numbers and completes the new Embedded Signup flow, the temporary object will be replaced by a WhatsApp Business Phone Number object and you must get the new object's ID in order to register the number .
verification_expiry_time
field
.Follow these steps to create a pre-verified business phone number, surface it in Embedded Signup, and register it after it has been claimed by an end client.
Use the Business Account > Add Phone Numbers endpoint to create a pre-verified business phone number on your business. This adds it to your pool of numbers.
POST /<BUSINESS_ACCOUNT_ID>/add_phone_numbers ?phone_number=<PHONE_NUMBER>
Upon success, the API will return a WhatsApp Business Pre-Verified Phone Number ID. Capture this value for use in the next request.
{ "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>" }
curl -X POST 'https://graph.facebook.com/ v20.0
/506914307656634/add_phone_numbers?phone_number=15550783881' \
-H 'Authorization: Bearer EAAJB...'
{ "id": "106540352242922" }
See the Business Account > Add Phone Numbers endpoint reference for supported phone number formats and query parameters.
Use the WhatsApp Business Pre-Verified Phone Number > Request Code endpoint to request a one-time-password over SMS or voice for the newly created pre-verified business phone number.
POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/request_code ?code_method=<CODE_METHOD> &language=<LANGUAGE>
Upon success, the API will return true
.
{ "success": <SUCCESS> }
In addition, we will send an SMS or voice message containing a one-time-password to the phone number. Capture the one-time-password for use in the next request.
WhatsApp code <CODE>
Repeated three times.
Verification code is <CODE>
curl -X POST 'https://graph.facebook.com/ v20.0
/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'
{ "success": true }
WhatsApp code 123-456
Repeated three times.
Verification code is 123456
See the WhatsApp Business Pre-Verified Phone Number > Request Code endpoint reference for supported code methods, languages, and query parameters.
Use the WhatsApp Business Pre-Verified Phone Number > Verify Code endpoint to verify the business phone number using its one-time-password.
POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/verify_code ?code=<CODE>
Upon success, the API will return true
and the business phone number will have its code_verification_status
set to VERIFIED
for 90 days.
{ "success": <SUCCESS> }
curl -X POST 'https://graph.facebook.com/ v20.0
/106540352242922/verify_code?code=123456' \
-H 'Authorization: Bearer EAAJB...'
{ "success": true }
See the WhatsApp Business Pre-Verified Phone Number > Verify Code endpoint reference for supported query parameters.
Once you have a pre-verified business phone number with a verified status (or a set of such numbers), display them in the new Embedded Signup flow.
You can display pre-verified business phone numbers in the new Embedded Signup flow through pre-filled form data
. To do this, add a preVerifiedPhone
object with an ids
property to the setup
object and assign the IDs of your pre-verified business phone numbers as an array of strings to the ids
property:
{ scope: '<SCOPE>', extras: { feature: '<FEATURE>', setup: { preVerifiedPhone: { ids: [<IDS>] } } } }
For example:
{ scope: 'business_management,whatsapp_business_management', extras: { feature: 'whatsapp_embedded_signup', version: 2, setup: { business: { name: 'Acme Inc.', email: 'johndoe@acme.com', phone: { code: 1, number: '6505551234' }, website: 'https://www.acme.com', address: { streetAddress1: '1 Acme Way', city: 'Acme Town', state: 'CA', zipPostal: '94000', country: 'US' }, timezone: 'UTC-08:00' }, phone: { displayName: 'Acme Inc.', category: 'ENTERTAIN', description: 'Gears and widgets' }, preVerifiedPhone: { ids: ['106540352242922','105954558954427'] } } } }
Note that if a pre-verified business phone number with a status of VERIFIED
is not claimed within 90 days of verification, its status will be set to UNVERIFIED
but it will still appear in the new Embedded Signup flow. If an end client attempts to claim an unverified number they must complete verification on their own, which means they must request a one-time password from you.
To prevent this poor user experience, we recommend that you keep track of when you verified a number and re-verify it before it reverts to an unverified state.
If you are uncertain of when you last verified a given pre-verified business phone number, query the WhatsApp Business Pre-Verified Phone Number
endpoint and read the code_verification_time
and verification_expiry_time
fields, which indicate its most recent verification time and its verification expiration time.
Perform a GET on the WhatsApp Business Account > Phone Numbers endpoint, which returns all WhatsApp Business Phone Numbers on a WhatsApp Business Account.
Parse for the display_phone_number
property in each object returned in the result set. If an object has the display phone number (e.g. 16505551234
) as its display_phone_number
value, it has been claimed. Copy the object's id
property value, since this is the ID for the new WhatsApp Business Phone Number object that now represents this number (the old ID will no longer work).
Alternatively, you can use the same endpoint with field
expansion to request the display_phone_number
field and specify the display phone number. For example:
GET /102290129340398/phone_numbers?display_phone_number=16505551234
If this returns a WhatsApp Business Phone Number object with that display phone number, the number has been claimed and you should copy the object's id
.
Use the Business Account > Preverified Numbers endpoint to get a list of all WhatsApp Business Pre-Verified Phone Number objects, regardless of their verification status, in your business account's pool of pre-verified business phone numbers:
GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers
Results are automatically sorted in order of creation time. You can also use field expansion to request the code_verification_status
field to have the API only return pre-verified business phone numbers with the indicated verification state:
GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers?code_verification_status=VERIFIED
Send a POST request to the Business > Share Preverified Numbers endpoint to share pre-verified business phone numbers with business partners, or a DELETE request to the same endpoint to unshare them.
Shared pre-verified business phone numbers can be surfaced in the Embedded Signup flow by business partners.
If you are sharing numbers with multiple business partners, we recommend that you advise your partners to get a list of shared pre-verified numbers before surfacing them in Embedded Signup. This reduces the likelihood of a partner attempting to surface a number that has already been claimed (claimed numbers do not appear in the flow, but the partner might not know this and wonder why it's not appearing).
POST /<BUSINESS_ID>/share_preverified_numbers ?partner_business_id=<PARTNER_BUSINESS_ID> &preverified_id=<PREVERIFIED_ID>
DELETE /<BUSINESS_ID>/share_preverified_numbers ?partner_business_id=<PARTNER_BUSINESS_ID> &preverified_id=<PREVERIFIED_ID>
Upon success, the API will return true. If sharing, notify your business partner of the newly shared preverified number and provide them with the number's ID. If unsharing, the number will no longer appear in the partner's implementation of Embedded Signup.
{ "success": <SUCCESS> }
curl -X POST 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \ -H 'Authorization: Bearer EAAH0...'
curl -X DELETE 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \ -H 'Authorization: Bearer EAAH0...'
{ "success": true }
You can bypass Embedded Signup phone number selection entirely and register pre-verified business phone numbers on an onboarded end client's WhatsApp Business Account programmatically. To do this, follow the steps in the Register Phone Numbers document, but use a pre-verified business phone number ID in Step 1, then skip to Step 4.
Use this request to create a WhatsApp Business Phone Number on a WhatsApp Business Account using a pre-verified business phone number ID. This replaces Step 1 .
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers
{ "preverified_id": "<PREVERIFIED_ID>", "country_dial_code": "<COUNTRY_DIAL_CODE>", "display_phone_number": "<DISPLAY_PHONE_NUMBER>", "verified_name": "<VERIFIED_NAME>" }
Placeholder | Description | Example Value |
---|---|---|
String |
Required. The pre-verified business phone number's ID. |
|
String |
Required. The pre-verified business phone number's country dial code. |
|
String |
Required. The pre-verified business phone number's display phone number. |
|
String |
Required. The pre-verified business phone number's display name. |
|
Upon success, the API will respond with the ID of a WhatsApp Business Phone Number . Use this ID to register the number ( Step 4in the Register Phone Numbers document).
{ "id": "<ID>" }
Placeholder | Description | Example Value |
---|---|---|
|
ID of a WhatsApp Business Phone Number . This object has replaced the WhatsApp Business Pre-Verified Phone Number object. |
|
curl 'https://graph.facebook.com/ v20.0
/506914307656634/phone_numbers' \
-H 'Content-Type: text/plain' \
-H 'Authorization: Bearer EAAH7...' \
-d '
{
"preverified_id": "6635066806614622",
"country_dial_code": "1",
"display_phone_number": "5550783881",
"verified_name": "Lucky Shrub"
}'
{ "id": "108692048990658" }