Managing business phone numbers

This guide provides overview information relating to phone numbers for Solution Partners and customers. Additionally, this guide contains process information for Solution Partners in the case that they have to manage a customer's phone number and certificates.

Preliminary information about business phone numbers

There are some details that businesses need to know surrounding phone numbers and Embedded Signup.

Businesses need a dedicated number to use WhatsApp through embedded signup. If a business has a number actively registered on WhatsApp Messenger or the WhatsApp Business App, they are not able to use the same phone number.

Businesses can have multiple phone numbers associated with their Meta Business Account, so all they have to do is add another phone number and use that for WhatsApp.

For more detailed information relating to phone numbers and WhatsApp for Business Platform, see Phone Numbers.

For information on how to migrate an existing registered WhatsApp phone number, see Migrate Phone Number.

Instructions for business customers

This section is directed towards customers of Embedded Signup and provides guidance about actions they may perform relating to phone numbers.

Add Phone Numbers to a WhatsApp Business Account

There are two methods to add additional numbers to a WhatsApp Business Account (WABA):

1. [Recommended] Go through the embedded signup flow again, select the existing Business Manager & WABA, add the number, and verify it.
2. In the Business Manager, go to the Phone Numbers tab of WhatsApp Manager, and select Add Phone Number. When using this option, the Solution Partner has to manually verify the phone number as phone verification is not available in the Business Manager. For this reason, it is recommended that businesses follow the embedded signup flow to add additional numbers.

Instructions for Solution Partners

This section is directed towards Solution Partners and provides instructions for managing customer phone numbers and certificates.

Getting phone numbers

Use the GET /<WABA_ID>/phone_numbers endpoint to get a list of business phone numbers on a business customer's WABA.

Request

curl 'https://graph.facebook.com/<API_VERSION>/<CUSTOMER_WABA_ID>/phone_numbers' \
-H 'Authorization: Bearer <CUSTOMER_BUSINESS_TOKEN>'

Response

Upon success:

{
  "data": [
    {
      "verified_name": "<VERIFIED_DISPLAY_NAME>",
      "code_verification_status": "<VERIFICATION_STATUS>",
      "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
      "quality_rating": "<QUALITY_RATING>",
      "platform_type": "CLOUD_API",
      "throughput": {
        "level": "<THROUGHPUT_LEVEL>"
      },
      "webhook_configuration": {
        "application": "<WEBHOOK_CALLBACK_URL>"
      },
      "id": "<BUSINESS_PHONE_NUMBER_ID>"
    }
  ],
  "paging": {
    "cursors": {
      "before": "<BEFORE_CURSOR>",
      "after": "<AFTER_CURSOR>"
    }
  }
}

Register phone numbers for Cloud API

After a successful phone verification from the embedded signup flow, registration should succeed with an API call to the register endpoint. For this, provide any code_method (sms | voice). Since the phone number is already verified, you do not need to worry about the registration code. The verify API call is not required.

Alternatively, you can pre-verify phone numbers and offer them to your customers in the new Embedded Signup flow. This prevents customers from having to contact you for a one-time password during the onboarding process. See Pre-Verified Phone Numbers.

Register phone numbers for On-Premises

After a successful phone verification from the embedded signup flow, registration should succeed with an API call to the account endpoint. For this, provide any code_method (sms | voice). Since the phone number is already verified, you do not need to worry about the registration code. The verify API call is not required.

Alternatively, you can pre-verify phone numbers and offer them to your customers in the new Embedded Signup flow. This prevents customers from having to contact you for a one-time password during the onboarding process. See Pre-Verified Phone Numbers.

Get phone's status and certificate

The phone_numbers endpoint allows you to see the status of a phone number's display name and to retrieve the certificate after a name change. See the Read Phone Numbers for more information.

Example request

In the following example, use the ID for the assigned WABA.

curl -i -X GET "https://graph.facebook.com/v21.0/{waba-id}/phone_numbers
  ?fields=
    display_phone_number,
    certificate,
    name_status,
    new_certificate,
    new_name_status
  &access_token={system-user-access-token}"

Example response

{
  "data": [
    {
      "id": "1972385232742141",    
      "display_phone_number": "+1 631-555-1111",
      "last_onboarded_time": "2023-08-22T19:05:53+0000",
      "certificate": "AbCdEfGhIjKlMnOpQrStUvWxYz",
      "new_certificate": "123AbCdEfGhIjKlMnOpQrStUvWxYz",
      "name_status": "APPROVED",
      "new_name_status": "APPROVED",
    }
  ]
}

Response parameters

Get phone's OTP status

To see if a phone number has been verified via OTP (one-time password), check that number’s code_verification_status field. First, make a GET call to the /{whatsapp-business-account-id}/phone_numbers endpoint:

curl -i -X GET \ 
"https://graph.facebook.com/v21.0/{waba-id}/phone_numbers
  ?access_token={your-access-token}"

The response includes the code_verification_status with one of the following options: VERIFIED or NOT_VERIFIED. A sample response looks like this:

[
  {
    "code_verification_status": "NOT_VERIFIED",
    "id": "1754951608042154"
  }
]

Alternatively, you can get the status by calling a phone number's ID:

curl -i -X GET \ 
"https://graph.facebook.com/v21.0/{phone-number-id}
  ?access_token={your-access-token}"

Filter phone numbers by account mode

You can query phone numbers and filter them based on their account_mode. For the request, you can use the parameters listed below.

Request parameters

Example request

In the following example, use the ID for the assigned WABA.

curl -i -X GET "https://graph.facebook.com/v21.0/{waba-id}/phone_numbers
  ?filtering=[{
    "field":"account_mode",
    "operator":"EQUAL",
    "value":"SANDBOX"}]
  &access_token={system-user-access-token}"

Example response

{
  "data": [
    {
      "id": "1972385232742141",    
      "display_phone_number": "+1 631-555-1111",
      "verified_name": "John’s Cake Shop",
      "quality_rating": "UNKNOWN",
    }
  ],
  "paging": {
	"cursors": {
		"before": "abcdefghij"
		"after": "klmnopqr"
	}
   }
}

Learn More

• Phone numbers: WhatsApp for Business Platform Overview
• Phone numbers: Migrate an existing registered number
• Reference: WhatsApp Business Account