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:

EdgeDescription

/verify

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:

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.

  1. Go to the Business Settings in your Facebook Business Manager.
  2. Click on WhatsApp Accounts under the Accounts menu, then select your WhatsApp Account from the WhatsApp Accounts list, if it isn't already highlighted.
  3. Go to the Settings tab, and click the WhatsApp Manager button.
  4. 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
  5. A pop-up dialog will display the certificate string in a gray box. Click Get Certificate.
    Download the Certificate String
  6. Use this certificate string in the cert parameter when registering with the account endpoint.

See the Display Name documentation for more information.

Constraints

  • You must use the admin account 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 the vname decoded from the cert parameter 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

NameDescription

cc

Required.

Numerical country code for the phone number you are registering

phone_number

Required.

Phone number you are registering, without the country code or plus symbol (+).

method

Required.

Method of receiving your registration code
Options: VOICE, SMS

cert

Required.

Base64-encoded certificate.

pin

Optional.

Existing 6-digit PIN — This is only required when two-step verification is enabled on this account.

Resetting Verification Code in WhatsApp Manager

If you forget or misplace your PIN, follow these steps to reset it in WhatsApp Manager:

  1. Go to settings, log into your Facebook Business, and click the business you are using to manage your WABA (WhatsApp Business Account)
  2. In the settings screen, click WhatApp Accounts and find the WABA you want to reset the verification code for. Click on the WABA and a panel with its respective info will come up on the right-side of the page
  3. In the WABA information module, click Settings
  4. In the new tab, click WhatsApp Manager
  5. In WhatsApp Manager, find your phone number and click Settings
  6. Click Two-step verification
  7. In the Two-step verification tab, click Turn off two-step verification. A message with instructions will be sent to your email address
  8. Your two-step verification code is now removed and depending on your platform, you can set it using one of these APIs:

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.

  1. In your WhatsApp Account, go to Settings.
  2. Click on WhatsApp Manager.
  3. 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.