We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.
Account
/v1/account
The account node is for registering your WhatsApp Business API client.
Please be aware that Coreapp will restart if a new number is registered on a cluster that has another number registered already.
Edges
The following edges are connected to this node:
| Edge | Description |
|---|---|
Once you have received the registration code via your specified method, use this edge to complete your account registration. |
Before You Start
You will need:
- Authentication Tokens to be able to login to the service
- A valid phone number associated with your WhatsApp Business Account
- A WhatsApp approved display name associated with that phone number
Copy the Base64-encoded Certificate
A base64-encoded certificate string is generated for you and is used for validation during WhatsApp Business API client registration.
- Go to the Business Settings in your Meta Business Manager.
- Click on WhatsApp Accounts under the Accounts menu, then select your WhatsApp Account from the WhatsApp Accounts list, if it isn't already highlighted.
- Go to the Settings tab, and click the WhatsApp Manager button.
- Under the Phone Numbers tab, you should see your phone numbers listed. Click the View button of the phone number you want the certificate for.
Get the Certificate - A pop-up dialog will display the certificate string in a gray box. Click Get Certificate.
Download the Certificate String - Use this certificate string in the
certparameter when registering with theaccountendpoint.
See the Display Name documentation for more information.
Constraints
- You must use the
adminaccount to register the application. - If you are re-registering your account, the Coreapp needs to be restarted once registration is complete.
Requesting
Make a POST call to this endpoint to request a registration code. In your call, add your phone number and base64-encoded certificate string. You can receive your code via either SMS or voice call.
Example
POST /v1/account
{
"cc": "COUNTRY_CODE",
"phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
"method": "sms" or "voice",
"cert": "VERIFIED_NAME_CERT_IN_BASE64",
"pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}
Depending on the response received, the registration procedure can be considered complete or require another step to complete. If successful, you receive one of the following HTTP status codes. Follow the instructions that match the response you received:
201 Created— The account already exists. You are already registered, so you do not need to do anything else.202 Accepted— The account does not exist. Depending on the method selected in the request, check your SMS or voice number for the registration code. This response will include a returned payload that contains thevnamedecoded from thecertparameter for you to confirm the right display name is being set. If correct, proceed to Completing Your Account Registration to complete registration.
{
"account": [{
"vname": "decoded-vname-from-cert"
}]
}
If any errors are returned, refer to Error and Status Messages for more information.
Parameters
| Name | Description |
|---|---|
| Required. Numerical country code for the phone number you are registering |
| Required. Phone number you are registering, without the country code or plus symbol ( |
| Required. Method of receiving your registration code |
| Required. Base64-encoded certificate. |
| Optional. Existing 6-digit PIN — This is only required when two-step verification is enabled on this account. |
Changing Your Two-Step Verification PIN
To change your business phone number's two-step verification PIN:
- Load the WhatsApp Business Account (WABA) associated with the phone number in WhatsApp Manager. See WhatsApp Manager if you have multiple portfolios and WABAs.
- Mousever the menu on the left and navigate to Account tools > Phone numbers.
- Use the dropdown menu on the top-right to select the WABA associated with the phone number, if necessary.
- Click the phone number's settings (gear) icon.
- Click Two-step verification.
- Click Change PIN and complete the flow.
You must supply your current PIN in order to change it. Note that you can also set a new PIN using our APIs:
Disabling Two-Step Verification
To disable two-step verification, 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.
FAQ
Yes, we can set up a new phone number or change the verified name when you are ready to go live.
Toll-free numbers are allowed as long as your country code is included. The reason is that toll-free numbers without country codes cannot be uniquely identified — the same number can apply for two different countries.
Also note that there are added complexities around toll-free numbers. Typically, if you call a toll-free number with the country code when you're inside the country, it will fail. This means that there is a chance your customers from your country will try to dial what shows in the business contact (country code included) and they won't be able to reach you. If this is a concern, you will need to let them know explicitly.
Read more about toll-free numbers here.
If you back up your current setup and restore it on the new machine, the registration information should move over with the rest of your implementation. See the Backup and Restore Settings documentation for more information.
You can register new phones numbers and delete old one in your WhatsApp Account in the Facebook Business Manager.
- In your WhatsApp Account, go to Settings.
- Click on WhatsApp Manager.
- Select the Phone Numbers tab. This is where you can manage all the phone numbers for this account.
If registration is failing with "sms" because of too many attempts and you see an "access denied" message, then please try registering with "voice"
Unfortunately, you will need to pick a different phone number that is capable of receiving SMS or voice in order for us to send the registration code. In the past, we had allowed manual registration codes, but this is no longer supported. Phone numbers that used manual registration codes before will continue to be supported as required. For any new phone numbers, we will only deliver registration codes via SMS or voice call.
If you want to use your 1800 or toll free number, please read this guide.