Update 05 February 2025

We have updated this article to reflect the latest changes in Meta Business Platform. The endpoints have been also tested to work with the Graph API versions 21 and 22 (upcoming).

This tutorial requires the use of the command-line interface. For Windows, we recommend instead to use PowerShell instead of the Command Prompt to use the Invoke-WebRequest command/cmdlet.

Warning: There are three different dashboards to interact with WhatsApp Business Platform. For the purpose of clarity, here's what we really meant about:

• Meta for Developers App Dashboard (formerly Facebook Developers App Dashboard): https://developers.facebook.com/apps
• Meta Business Suite (formerly Facebook Business): https://business.facebook.com/latest/home
• WhatsApp Manager: https://business.facebook.com/latest/whatsapp_manager (formerly https://business.facebook.com/wa/manage)

The WhatsApp Business platform also consists of different set of credentials as listed below. Here, we only need to use the Access Token, the WhatsApp Phone Number ID (not the Business Account ID), and the WhatsApp Two-Step Verification PIN (more on that later).

• Access Token: In order to perform HTTP request to WhatsApp Business Platform.
  • The Meta for Developers App Dashboard by default allows you to create temporary tokens for use in 24 hours.
  • To create a permanent access token:
    • Ensure that your Facebook account is connected to both the Meta Business Suite (to manage business entities) and Meta for Developers App Dashboard (i.e. by registering into the Meta/Facebook Developers programme).
    • Register a new business and Business Assets (i.e. related Facebook pages and Instagram accounts) on Meta Business Suite.
    • Register a new app on Meta for Developers App Dashboard
    • Create a new System User on the Business Settings in the Meta Business Suite
    • On the Meta Business Suite, create the Access Token by clicking on Generate Token button on the System User settings, then link them to the desired App.
• App Secret (as configured in the App Dashboard): Only useful when authenticating received webhooks.
• Webhook Verify Token: A unique token set by you to be able to verify certain webhook events.
• WhatsApp Business Account ID: The Facebook Graph API Object ID representing the business account.
  • This ID can be easily grabbed on the Meta App Dashboard, assuming that you have registered the phone number.
• WhatsApp Phone Number ID: The Facebook Graph API Object ID representing the registered phone number.
  • This ID can be easily grabbed on the Meta App Dashboard, assuming that you have registered the phone number.
• WhatsApp Two-Step Verification PIN: A 6-digit PIN set by you to secure your WhatsApp business account.

If you are not familiar, the Facebook Graph API introduced an universal ID format for every kinds of object/entities. That means if there is a WhatsApp Business Account ID of 123123123, then it is guaranteed that the number are not used in any other forms of objects, like the WhatsApp Phone Number ID, the Facebook Pages ID, the Instagram Post ID, and so on.

Step 1: Request a display name change on WhatsApp Manager.

You cannot try this feature on the default Test WhatsApp Business Account or any account that has the Display Name change featured disabled for administrative reasons.

Go to WhatsApp Manager > Account Tools > Phone Numbers. Make sure that you are selecting the correct WhatsApp Account on the top-right corner.

You can also see that there's the "WhatsApp account ID", which is actually your WhatsApp Business Account ID. It is different than WhatsApp Phone Number ID that we need later, as some WhatsApp Business Account are allowed to add more than one phone numbers.

Now, on your desired phone number, change the display name. You can only move to the next step if the new display name is approved.

So, where is your WhatsApp Phone Number ID?

Due to the recent changes on the Meta Business Suite, the only way to view your WhatsApp Phone Number ID is by going to the Meta for Developers App Dashboard then select your resently-created app, then go to WhatsApp > API Setup on your dashboard.

On the Send and Receive Messages section, choose the desired phone number. You can finally reveal both WhatsApp Business Account ID and the WhatsApp Phone Number ID of the linked phone number.

Step 2: Set-up Two-Step Verification PIN (for existing accounts).

Existing WhatsApp Business Platform accounts (which have not set the PIN yet) should invoke the following command first.

This is the part where we start to use the command-line.

Replace the {{ACCESS_TOKEN}}, {{PHONE_NUMBER_ID}} and {{PIN}} with the Access Token, WhatsApp Phone Number ID, and WhatsApp Two-Step Verification PIN respectively.

# Windows (requires PowerShell)
Invoke-WebRequest -Method Post -Body '{ "pin": "{{PIN}}" } -Headers @{ Authorization = "Bearer {{ACCESS_TOKEN}}" } -ContentType 'application/json' https://graph.facebook.com/v20.0/{{PHONE_NUMBER_ID}}

# macOS and Linux (requires curl)
curl 'https://graph.facebook.com/v20.0/{{PHONE_NUMBER_ID}}' -H 'Content-Type: application/json' -H 'Authorization: Bearer {{ACCESS_TOKEN}}' -d '{ "pin": "{{PIN}}" }'

Make sure that the server responds with {"success":true}.

Note that the above step is only valid for existing phone numbers (newly registered phone numbers will have their PIN set up on the next step). Or else, you may get the following error:

{"error":{"message":"The account is not registered","type":"OAuthException","code":133010,"error_subcode":2593006,"is_transient":false,"error_user_title":"Account does not exist","error_user_msg":"Account does not exist in Cloud API. Please use\/register API to create an account first.","fbtrace_id":"..."}}

Step 3: Trigger the WhatsApp profile change with a Two-Step Verification PIN.

Replace the {{ACCESS_TOKEN}}, {{PHONE_NUMBER_ID}} and {{PIN}} with the Access Token, WhatsApp Phone Number ID, and WhatsApp Two-Step Verification PIN respectively.

• For existing phone numbers, you should use the existing WhatsApp Two-Step Verification PIN in the {{PIN}} attribute as shown below.
• For newly-registered phone numbers, the {{PIN}} is where you will set a new WhatsApp Two-Step Verification PIN.

You do not need to download/use certificates!

Yes, you do not need to either download, copy, or use the given certificates as they are good only for WhatsApp Business On-Premises API, which is currently being sunset by Meta in favor of this Cloud API.

Additionally, Meta has decided to block the On-Premises API from accepting new phone number registrations. For more information, see Meta for Developers docs.

# Windows (requires PowerShell)
Invoke-WebRequest -Method Post -Body '{ "messaging_product": "whatsapp", "pin": "{{PIN}}" } -Headers @{ Authorization = "Bearer {{ACCESS_TOKEN}}" } -ContentType 'application/json' https://graph.facebook.com/v20.0/{{PHONE_NUMBER_ID}}/register

# macOS and Linux (requires curl)
curl 'https://graph.facebook.com/v20.0/{{PHONE_NUMBER_ID}}/register' -H 'Content-Type: application/json' -H 'Authorization: Bearer {{ACCESS_TOKEN}}' -d '{ "messaging_product": "whatsapp", "pin": "{{PIN}}" }'

Updating the Two-Step Verification PIN at anytime.

Since your account is now directly managed by Meta, you will not need to worry of being unable to recover your lost PIN. However, changing PINs are currently only possible on the WhatsApp Manager, not the Cloud API itself. It is located on WhatsApp Manager > Phone Numbers > Two-step verification, which the menu might be hidden inside the More dropdown.