Pre-Verified Phone Numbers

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.

Requirements

• Your business must be an approved Solution Partner.
• The app user must be a business admin on the business account that pre-verified business phone numbers are added to.
• A User or System User access token.
• The business_management permission.
• Business phone numbers must be valid.

Limitations

• Only available with the new Embedded Signup flow. See the Embed the Signup Flow document to learn how to enable the new flow.
• You are responsible for keeping track of who has claimed a pre-verified business phone number.
• If a pre-verified business phone number is not claimed by an end client in the Embedded Signup flow within 90 days of verification, the number will revert to an unverified status and must be verified again to have its status restored for another 90 days.
• Unclaimed pre-verified business phone numbers can't be re-verified until 45 days before they are scheduled to revert to an unverified status. This time is indicated by the verification_expiry_time field.
• If you add a phone number to your pool of pre-verified business phone numbers (Step 1) but do not verify it within 90 days (Step 3), it will be removed from your pool and you will have to add it again.

Creating Pre-Verified Numbers

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.

Step 1: Create a pre-verified business phone number

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.

Request Syntax

POST /<BUSINESS_ACCOUNT_ID>/add_phone_numbers
  ?phone_number=<PHONE_NUMBER>

Response

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>"
}

Sample Request

curl -X POST 'https://graph.facebook.com/v19.0/506914307656634/add_phone_numbers?phone_number=15550783881' \
-H 'Authorization: Bearer EAAJB...'

Sample Response

{
  "id": "106540352242922"
}

See the Business Account > Add Phone Numbers endpoint reference for supported phone number formats and query parameters.

Step 2: Request a verification code

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.

Request Syntax

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/request_code
  ?code_method=<CODE_METHOD>
  &language=<LANGUAGE>

Response

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.

One-Time-Password SMS Syntax

WhatsApp code <CODE>

One-Time-Password Voice Message Syntax

Repeated three times.

Verification code is <CODE>

Sample Request

curl -X POST 'https://graph.facebook.com/v19.0/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

Sample Response

{
  "success": true
}

Sample One-Time-Password SMS Message

WhatsApp code 123-456

Sample One-Time-Password Voice Message

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.

Step 3: Verify the number

Use the WhatsApp Business Pre-Verified Phone Number > Verify Code endpoint to verify the business phone number using its one-time-password.

Request Syntax

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/verify_code
  ?code=<CODE>

Response

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>
}

Sample Request

curl -X POST 'https://graph.facebook.com/v19.0/106540352242922/verify_code?code=123456' \
-H 'Authorization: Bearer EAAJB...'

Sample Response

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

Displaying pre-verified numbers in Embedded Signup

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.

Determining if a number has been claimed through Embedded Signup

See Getting claimed phone number IDs.

Getting Claimed Phone Number IDs

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.

Get Pre-Verified Business Phone Numbers

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

Sharing and Unsharing Pre-Verified Numbers

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

Sharing Request Syntax

POST /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Unsharing Request Syntax

DELETE /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Response

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>
}

Example Sharing Request

curl -X POST 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Example Unsharing Request

curl -X DELETE 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Example Response

{
  "success": true
}

Registering Pre-Verified Numbers Programmatically

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.

Request Syntax

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

Post Body

{
  "preverified_id": "<PREVERIFIED_ID>",
  "country_dial_code": "<COUNTRY_DIAL_CODE>",
  "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
  "verified_name": "<VERIFIED_NAME>"
}

Properties

Response Syntax

Upon success, the API will respond with the ID of a WhatsApp Business Phone Number. Use this ID to register the number (Step 4 in the Register Phone Numbers document).

{
  "id": "<ID>"
}

Response Properties

Example Request

curl 'https://graph.facebook.com/v19.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"
}'

Example Response

{
  "id": "108692048990658"
}