Phone Numbers

This guide specifies how you can verify your phone number and its required formatting for the Cloud API.

There is a criteria for what kind of phone numbers you can add to your WhatsApp Business Account (WABA). Please see Phone Numbers for further information.

Some API calls listed require you to know your phone number’s ID. Refer to Get All Phone Numbers on how to get the phone numbers associated with your WABA. The API call response includes IDs for each of the phone numbers connected to your WhatsApp Business Account. Save the ID for the phone you want to use with any /PHONE_NUMBER_ID calls.

Verify Phone Numbers

You need to verify the phone number you want to use to send messages to your customers. Phone numbers must be verified using a code sent via an SMS/voice call. The verification process can be done via Graph API calls specified below.

To verify a phone number using Graph API, make a POST request to PHONE_NUMBER_ID/request_code. In your call, include your chosen verification method and locale.

EndpointAuthentication

/PHONE_NUMBER_ID/request_code

Authenticate yourself with a system user access token.


If you are requesting the code on behalf of another business, the access token needs to have Advanced Access to the whatsapp_business_management permission.

Parameters

NameDescription (Click the arrow in the left column for supported options.)

code_method

string

Required.

Chosen method for verification.

Supported Options

  • SMS
  • VOICE

locale

string

Required.

Your locale. For example: "en_US".

Example

Sample request:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/request_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code_method=SMS' 
  -F 'locale=en_US'

After the API call, you will receive your verification code via the method you selected. To finish the verification process, include your code in a POST request to PHONE_NUMBER_ID/verify_code.

EndpointAuthentication

/PHONE_NUMBER_ID/verify_code

Authenticate yourself with a system user access token.


If you are requesting the code on behalf of another business, the access token needs to have Advanced Access to the whatsapp_business_management permission.

Parameters

NameDescription

code

numeric string

Required.

The code you received after calling FROM_PHONE_NUMBER_ID/request_code.

Example

Sample request:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/verify_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code=000000'

A successful response looks like this:

{
  "success": True
}

Formatting

The phone numbers in Cloud API requests can be provided in any dialable format, as long as they include their country code.

Here are some examples of supported phone number formats:

  • "1-000-000-0000"
  • "1 (000) 000-0000"
  • "1 000 000 0000"
  • "1 (000) 000 0000"