This document describes the steps to programmatically register business phone numbers on WhatsApp Business Accounts (WABA).
Note that Embedded Signup performs steps 1-3 automatically (unless you are bypassing the phone number addition screen) so you only need to perform step 4 when a business customer completes the flow. If you have disabled phone number selection, however, you must perform all 4 steps.
Registering business phone numbers is a four step process:
These steps are described below.
You can also perform all 4 steps repeatedly to register business phone numbers in bulk.
Business phone numbers must meet our phone number requirements.
Send a POST request to the WhatsApp Business Account > Phone Numbers endpoint to create a business phone number on a WABA.
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers
{ "cc": "<CC>", "phone_number": "<PHONE_NUMBER>", "verified_name": "<VERIFIED_NAME>" }
Placeholder | Description | Example Value |
---|---|---|
String | Required. The phone number's country calling code. |
|
String | Required. The phone number, with or without the country calling code. |
|
String | Required. The phone number's display name. |
|
Upon success, the API returns a business phone number ID. Capture this ID for use in the next step.
{ "id": "<ID>" }
Placeholder | Description | Example Value |
---|---|---|
| An unverified WhatsApp Business Phone Number ID. |
|
curl 'https://graph.facebook.com/v21.0
/102290129340398/phone_numbers' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAH7...' \
-d '{
"cc": "1",
"phone_number": "14195551518",
"verified_name": "Lucky Shrub"
}'
{ "id": "110200345501442" }
Send a POST request to the WhatsApp Business Phone Number > Request Code endpoint to have a verification code sent to the business phone number.
POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/request_code ?code_method=<CODE_METHOD> &language=<LANGUAGE>
Placeholder | Description | Example Value |
---|---|---|
| Required. Indicates how you want the verification code delivered to the business phone number. Values can be |
|
| Required. Indicates language used in delivered verification code. |
|
{ "success": <SUCCESS> }
Placeholder | Description | Example Value |
---|---|---|
| Boolean indicating success or failure. Upon success, the API will respond with |
|
curl -X POST 'https://graph.facebook.com/v21.0
/110200345501442/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'
{ "success": true }
Example of an SMS message in English containing a verification code, delivered to a business phone number:
WhatsApp code 123-830
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.
POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/verify_code ?code=<CODE>
Placeholder | Description | Example Value |
---|---|---|
String | Required. Verification code, without the hyphen. |
|
{ "success": <SUCCESS> }
Placeholder | Description | Example Value |
---|---|---|
| Boolean indicating success or failure. Upon success, the API will respond with |
|
curl -X POST 'https://graph.facebook.com/v21.0
/110200345501442/verify_code?code=123830' \
-H 'Authorization: Bearer EAAJB...'
{ "success": true }
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.
POST /<BUSINESS_PHONE_NUMBER_ID>/register
{ "messaging_product": "whatsapp", "pin": "<PIN>" }
Placeholder | Description | Example Value |
---|---|---|
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. |
|
Upon success, the API will respond with true
, indicating successful registration.
{ "success": <SUCCESS> }
Placeholder | Description | Example Value |
---|---|---|
| Boolean indicating success or failure. Upon success, the API will respond with |
|
curl 'https://graph.facebook.com/v21.0
/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
"messaging_product": "whatsapp",
"pin": "123456"
}'
{ "success": true }