Business phone numbers

This document describes WhatsApp business phone numbers, their requirements, management instructions, and features.

Registering business phone numbers

A valid business phone number must be registered before it can be used to send and receive messages via Cloud API. Registered numbers can still be used for everyday purposes, such as calling and text messages, but cannot be used with WhatsApp Messenger ("WhatsApp").

Numbers already in use with WhatsApp cannot be registered unless they are deleted first. If your number is banned on WhatsApp and you wish to register it, it must be unbanned via the appeal process first.

Note that when you complete the steps in our Get Started document, a test business phone number will be generated and registered for you automatically.

Eligibility requirements

Eligible phone numbers must be:

owned by you
have a country and area code (short codes are not supported)
able to receive voice calls or SMS

If you are registering a 1-800 number, see Registering 1-800 and Toll Free Numbers for additional information.

Registration methods

App Dashboard: Complete the steps in our Get Started document if you haven't already, then use the App Dashboard > WhatsApp > API Setup panel to add a phone number.
Meta Business Suite: You can register a business phone number when using Meta Business Suite to create a WhatsApp Business Account.
WhatsApp Manager: See our How to connect your phone number to your WhatsApp Business Account help center article.
Embedded Signup: If you are working with a solution partner, they will provide you with a link to Embedded Signup, which you can use to register a number.

Status

Business phone numbers have a status, which reflects their quality rating and current messaging limit. Business phone numbers must have a status of "connected" in order to send and receive messages via the API.

Viewing status via WhatsApp Manager

Your business phone number's current status appears in the Status column in the WhatsApp Manager > Account tools > Phone numbers panel.

See our About your WhatsApp Business phone number’s quality rating help center article to learn more about quality ratings and statuses as they appear in WhatsApp Manager.

Getting status via API

Request the status field on your WhatsApp Business Phone Number ID. See the GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID> reference for a list of returnable status values and their meanings.

Example request

curl 'https://graph.facebook.com/v23.0/106540352242922?fields=status' \\
-H 'Authorization: Bearer EAAJB...'

Example response

{
  "status": "CONNECTED",
  "id": "106540352242922"
}

Monitoring status changes

See our monitoring quality signals document to learn how you can monitor changes to your business phone number's status.

Display names

You must provide a display name when registering a business phone number. The display name can appear in your business phone number's WhatsApp profile:

It can also appear at the top of individual chat threads and the chat list if your business phone number is approved for Official Business Account status. Note that if a WhatsApp user edits your profile name in the WhatsApp client, the name they set will appear instead.

Display name guidelines

See our Display name guidelines for the WhatsApp Business Platform help center article for naming guidelines.

Display name verification

When you register a business phone number or edit your existing display name, the new display name will automatically undergo verification based on our display name guidelines. When we complete the process, a phone_number_name_update webhook and Meta Business Suite notification will be triggered.

If your display name is approved, the webhook will have decision set to APPROVED, and we will set the name_status field on your business phone number to APPROVED.

If your display name is rejected, the webhook will have decision set to REJECTED, and we will set the name_status field on your business phone number to DECLINED. If your name is rejected, we recommend that you re-review our display name guidelines and edit your display name accordingly, or file an appeal via Developer Support or Enterprise Developer Support.

Viewing display name in WhatsApp Manager

Your business phone number's display name appears in the Name column in the WhatsApp Manager > Account tools > Phone numbers panel.

Getting display name and display name status via API

Request the verified_name and name_status field on your WhatsApp Business Phone Number ID to get its display name and display name status. See the GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID> reference for a list of returnable values and their meanings.

Note that the verified_name value does not indicate if the display name is approved or not, it just represents the display name string submitted for approval. The name_status field indicates its approval status.

Example request

curl 'https://graph.facebook.com/v23.0/106540352242922?fields=verified_name,name_status \\
-H 'Authorization: Bearer EAAJB...'

Example response

Upon success:

{
  "verified_name": "Lucky Shrub",
  "name_status": "APPROVED",
  "id": "106540352242922"
}

Updating display name via WhatsApp Manager

To update your display name via WhatsApp Manager:

Navigate to WhatsApp Manager > Account tools > Phone numbers.
Select your business phone number.
Click the Profile tab.
In the Display name section, click the Edit button and complete the flow.

Once you complete the flow, your display name will undergo display name verification again.

Updating display name via API

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID> endpoint's new_display_name field to update your display name via API.

Example request

curl -X POST 'https://graph.facebook.com/v23.0/179776755229976?new_display_name=Lucky%20Shrub' \\
-H 'Authorization: Bearer EAAJB...'

Example response

Upon success:

{
  "success": true
}

Upon success, your display name will undergo display name verification. If you want to check the verification status, request the new_display_name and new_name_status fields on your business phone number ID:

Example request

curl 'https://graph.facebook.com/v21.0/106540352242922?fields=new_display_name,name_status \\
-H 'Authorization: Bearer EAAJB...'

Example response

Upon success:

{
  "new_display_name": "New Lucky Shrub",
  "new_name_status": "PENDING_REVIEW",
  "id": "106540352242922"
}

If your newly updated display name is approved, your business phone number's verified_name and name_status fields will be updated to reflect your new display name and name status, and phone_number_name_update webhooks will be triggered.

Business profiles

Your business phone number's business profile provides additional information about your business, such as its address, website, description, etc.

Viewing or updating your profile via WhatsApp Manager

To view or update your business profile via WhatsApp Manager:

Navigate to WhatsApp Manager > Account tools > Phone numbers.
Select your business phone number.
Click the Profile tab to view your current profile.
Use the form to set new profile values.

Getting your profile via API

Use the GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/whatsapp_business_profile endpoint to request specific business profile fields:

Example request

curl 'https://graph.facebook.com/v23.0/106540352242922/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical' \\
-H 'Authorization: Bearer EAAJB...'

Example response

Upon success:

{
  "data": [
    {
      "about": "Succulent specialists!",
      "address": "1 Hacker Way, Menlo Park, CA 94025",
      "description": "At Lucky Shrub, we specialize in providing a...",
      "email": "lucky@luckyshrub.com",
      "profile_picture_url": "https://pps.whatsapp.net/v/t61.24...",
      "websites": [
        "https://www.luckyshrub.com/"
      ],
      "vertical": "RETAIL",
      "messaging_product": "whatsapp"
    }
  ]
}

Updating your profile via API

Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/whatsapp_business_profile endpoint to update specific business profile fields:

Example request

curl 'https://graph.facebook.com/v23.0/106540352242922/whatsapp_business_profile' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer EAAJB...' \\
--data-raw '
{
  "about": "Succulent specialists!",
  "address": "1 Hacker Way, Menlo Park, CA 94025",
  "description": "At Lucky Shrub, we specialize in...",
  "email": "lucky@luckyshrub.com",
  "messaging_product": "whatsapp",
  "profile_picture_handle": "4::aW1hZ2U...",
  "vertical": "RETAIL",
  "websites": "[\n  \"https://www.luckyshrub.com\"\n]"
}'

Example response

Upon success:

{
  "success": true
}

Two-step verification

You must set a two-step verification PIN when registering a business phone number. Your PIN is required when changing your PIN or deleting your phone number from the platform.

Changing your PIN via WhatsApp Manager

You will need your current PIN to change your PIN via WhatsApp Manager. To change your PIN:

Navigate to WhatsApp Manager > Account tools > Phone numbers.
Select your business phone number.
Click the Two-step verification tab.
Click the Change PIN button and complete the flow.

If you don't have your PIN, you can change your PIN using the API.

Changing your PIN via API

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID> endpoint to set a new PIN.

Example request

curl 'https://graph.facebook.com/v23.0/106540352242922/' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer EAAJB...' \\
-d '
{
  "pin": "150954"
}'

Example response

Upon success:

{
  "success": true
}

Disabling Two-Step Verification

To disable two-step verification using WhatsApp Manager, follow the steps for changing your PIN, but click the Turn off two-step verification button as the final step instead. An email with a link will be sent to the email address associated with your business portfolio. Use the link to disable two-step verification. Once disabled, you can re-enable it by setting a new PIN.

Note that you cannot disable two-step verification using the API.

1-800 and Toll Free Numbers

You may want to register a 1-800 or other toll free number on the platform. These numbers are usually behind an Interactive Voice Response (IVR) system, however, which a WhatsApp registration call cannot navigate. Phone numbers behind an IVR system can be registered, but must be able to accept calls from international numbers and be able to redirect our SMS message or voice call to a real person.

To register a phone number that is behind an IVR system:

WhatsApp shares with you 1 or 2 phone numbers that the registration call will come from.
Create an allow list for these numbers. If you are unable to create an allow list for these numbers, add the phone number to your WABA and open a Direct Support ticket asking for the registration call phone numbers and include the phone number you are trying to register in the ticket.
Redirect the registration call to an employee or a mailbox to capture the registration code.

Phone numbers behind an IVR system that are unable to receive registration calls are not supported.

Registered number cap

Business phone numbers can only be registered for use with one API at a time: Cloud API or On-Premises API.

Business portfolios are initially limited to 2 registered business phone numbers, but this limit can be increased to up to 20.

If your business has been verified, or if you open 1,000 or more business-initiated conversations in a 30-day moving period using templates with a high quality rating, we will determine if your API usage warrants a phone number limit increase.

If we determine an increase is warranted, we will automatically increase your limit and notify you by business_capability_update webhook and Meta Business Suite notification of your new limit.

If we determine that an increase is not warranted, we will keep your limit at 2. If more than a week has passed since your business has been verified and your limit is still 2, ensure that you are monitoring phone number and message quality and take appropriate actions to improve your quality scores. After improving your quality scores, if we determine that your business warrants an increase, we will automatically increase your limit and notify you by webhook and Meta Business Suite notification of the new limit.

If you have access to Enterprise Support and need your limit increased beyond 20, open a Direct Support Ticket with the following selections and explain why you need more than 20 numbers:

WABiz: Account & WABA > Request type > Increase Phone Number Limits

Deleting business phone numbers

Only business portfolio admins can delete business phone numbers, and numbers can't be deleted if they have been used to send paid messages within the last 30 days.

Deleting business phone numbers via WhatsApp Manager

If your business phone number has a Connected status, you will need your two-step verification PIN to delete your number.

Load your business portfolio in the WhatsApp Manager.
If it doesn't automatically load the Phone numbers panel, navigate to Account tools (the toolbox icon) > Phone numbers.
Click the phone number's trash can icon and complete the flow.

If the number has been used to send paid messages within the last 30 days, you will be redirected to the Insights panel, showing the date of the last paid message. You can delete the number 30 days from this date.

Deleting business phone numbers via API

You cannot delete a business phone number via API.

Migrating business phone numbers

You can migrate phone numbers from one WABA to another, as well as migrate a number from On-Premises API to Cloud API (or vice-versa).

Conversational Components

You can enable helpful message UI components to make it easier for WhatsApp users to interact with your business. See Conversational Components.

WhatsApp Business Platform | Cloud API | On-Premises API | Business Management API