WhatsApp Business Platform

Registering Phone Numbers

This document explains how to programmatically register business phone numbers on WhatsApp Business Accounts (WABA).

Registering phone numbers is a four step process:

  1. Create the number on a WABA.
  2. Get a verification code for that number.
  3. Use the code to verify the number.
  4. Register the verified number for use with Cloud API or On-Premises API.

These steps are described below.

Note that Embedded Signup performs steps 1-3 automatically (unless you've disabled phone number selection) so you only need to perform step 4 when an end client completes the flow. If you have disabled phone number selection, however, you must perform all 4 steps.

You can also perform all 4 steps repeatedly to register business phone numbers in bulk.

Limitations

Business phone numbers must meet our phone number requirements.

Step 1: Create the phone number

Send a POST request to the WhatsApp Business Account > Phone Numbers endpoint to create a business phone number on a WABA.

Request Syntax

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

Post Body

{
  "cc": "<CC>",
  "phone_number": "<PHONE_NUMBER>",
  "verified_name": "<VERIFIED_NAME>"
}

Body Properties

PlaceholderDescriptionExample Value

<CC>

String

Required.


The phone number's country calling code.

1

<PHONE_NUMBER>

String

Required.


The phone number, with or without the country calling code.

15551234

<VERIFIED_NAME>

String

Required.


The phone number's display name.

Lucky Shrub

Response

Upon success, the API returns a business phone number ID. Capture this ID for use in the next step.

{
  "id": "<ID>"
}

Response Properties

PlaceholderDescriptionExample Value

<ID>

An unverified WhatsApp Business Phone Number ID.

106540352242922

Example Request

curl 'https://graph.facebook.com/v19.0/102290129340398/phone_numbers' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAH7...' \
-d '{
    "cc": "1",
    "phone_number": "14195551518",
    "verified_name": "Lucky Shrub"
}'

Example Response

{
  "id": "110200345501442"
}

Step 2: Request a verification code

Send a POST request to the WhatsApp Business Phone Number > Request Code endpoint to have a verification code sent to the business phone number.

Request Syntax

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

Query String Parameters

PlaceholderDescriptionExample Value

<CODE_METHOD>

Required.


Indicates how you want the verification code delivered to the business phone number. Values can be SMS or VOICE.

SMS

<LANGUAGE>

Required.


Indicates language used in delivered verification code.

en_US

Response

{
  "success": <SUCCESS>
}

Response Properties

PlaceholderDescriptionExample Value

<SUCCESS>

Boolean indicating success or failure.


Upon success, the API will respond with true and a verification code will be sent to the business phone number using the method specified in your request.

true

Example Request

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

Example Response

{
  "success": true
}

Example SMS Delivery

Example of an SMS message in English containing a verification code, delivered to a business phone number:

WhatsApp code 123-830

Step 3: Verify the number

Send a POST request to the WhatsApp Business Phone Number > Verify Code endpoint to verify the business phone number, using the verification code contained in the SMS or voice message delivered to the number.

Request Syntax

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

Query String Parameters

PlaceholderDescriptionExample Value

<CODE>

String

Required.


Verification code, without the hyphen.

123830

Response

{
  "success": <SUCCESS>
}

Response Properties

PlaceholderDescriptionExample Value

<SUCCESS>

Boolean indicating success or failure.


Upon success, the API will respond with true, indicating that the business phone number has been verified.

true

Example Request

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

Example Response

{
  "success": true
}

Step 4: Register the number

Send a POST request to the WhatsApp Business Phone Number > Register endpoint to register the business phone number for use with Cloud API.

If registering the business phone number for use with On-Premises API, see the On-Premises API Account endpoint reference for instructions.

Request Syntax

POST /<BUSINESS_PHONE_NUMBER_ID>/register

Post Body

{
  "messaging_product": "whatsapp",
  "pin": "<PIN>"
}

Body Properties

PlaceholderDescriptionExample Value

<PIN>

String

Required.


If the verified business phone number already has two-step verification enabled, set this value to the number's 6-digit two-step verification PIN. If you do not recall the PIN, you can update it.


If the verified business phone number does not have two-step verification enabled, set this value to a 6-digit number. This will be the business phone number's two-step verification PIN.

123456

Response

Upon success, the API will respond with true, indicating successful registration.

{
  "success": <SUCCESS>
}

Response Properties

PlaceholderDescriptionExample Value

<SUCCESS>

Boolean indicating success or failure.


Upon success, the API will respond with true, indicating successful registration.

true

Example Request

curl 'https://graph.facebook.com/v19.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "123456"
}'

Example Response

{
  "success": true
}