This document describes WhatsApp business phone numbers, their requirements, management instructions, and features.
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.
Eligible phone numbers must be:
If you are registering a 1-800 number, see Registering 1-800 and Toll Free Numbers for additional information.
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.
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.
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.
curl 'https://graph.facebook.com/v23.0
/106540352242922?fields=status' \\
-H 'Authorization: Bearer EAAJB...'
{ "status": "CONNECTED", "id": "106540352242922" }
See our monitoring quality signals document to learn how you can monitor changes to your business phone number's status.
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.
See our Display name guidelines for the WhatsApp Business Platform help center article for naming guidelines.
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.
Your business phone number's display name appears in the Name column in the WhatsApp Manager > Account tools > Phone numbers panel.
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.
curl 'https://graph.facebook.com/v23.0
/106540352242922?fields=verified_name,name_status \\
-H 'Authorization: Bearer EAAJB...'
Upon success:
{ "verified_name": "Lucky Shrub", "name_status": "APPROVED", "id": "106540352242922" }
To update your display name via WhatsApp Manager:
Once you complete the flow, your display name will undergo display name verification again.
Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID> endpoint's new_display_name
field to update your display name via API.
curl -X POST 'https://graph.facebook.com/v23.0
/179776755229976?new_display_name=Lucky%20Shrub' \\
-H 'Authorization: Bearer EAAJB...'
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:
curl 'https://graph.facebook.com/v21.0/106540352242922?fields=new_display_name,name_status \\ -H 'Authorization: Bearer EAAJB...'
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.
Your business phone number's business profile provides additional information about your business, such as its address, website, description, etc.
To view or update your business profile via WhatsApp Manager:
Use the GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/whatsapp_business_profile endpoint to request specific business profile fields:
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...'
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" } ] }
Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/whatsapp_business_profile endpoint to update specific business profile fields:
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]"
}'
Upon success:
{ "success": true }
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.
You will need your current PIN to change your PIN via WhatsApp Manager. To change your PIN:
If you don't have your PIN, you can change your PIN using the API.
Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID> endpoint to set a new PIN.
curl 'https://graph.facebook.com/v23.0
/106540352242922/' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer EAAJB...' \\
-d '
{
"pin": "150954"
}'
Upon success:
{ "success": true }
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.
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:
Phone numbers behind an IVR system that are unable to receive registration calls are not supported.
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
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.
If your business phone number has a Connected status, you will need your two-step verification PIN to delete your number.
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.
You cannot delete a business phone number via API.
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).
You can enable helpful message UI components to make it easier for WhatsApp users to interact with your business. See Conversational Components.