Registration

/v1/account

You can use the account node to register the application.

This document covers:

You must use the admin account to register the application.

Authentication Tokens

To use the WhatsApp Business API, you must first authenticate your WhatsApp Business API Client with the server and receive a token that enables you to access the service.

See the Login and Authentication documentation for more information about authentication.

Phone Number and VName Certificate

To register, you must have a valid phone number and the base64-encoded Verified Name (vname) certificate associated with that phone number.

The phone number must be able to receive sms or voice calls directly. You will not be able to use numbers that are behind IVR like 1-800 or other toll-free numbers. However, If you have a phone number already registered using a manual code before, it will continue to work normally.

Add Your Phone Number

  1. Go to the Business Settings in the Facebook Business Manager.
  2. Select your WhatsApp Account from the WhatsApp Accounts list, if it isn't already.
  3. Under Manage People and Settings, select Settings.
  4. Click WhatsApp Manager.
  5. Under the Phone Numbers tab, click Add New Number.
    Add New Number
  6. For Phone Number, select your country code from the drop-down and enter the phone number you want to register in the text box.
  7. Enter the name of your business in the Business Name text box.
  8. Click Add.

You should now see your phone number and its status listed.

See the Phone Number documentation for more information.

Copy the Base64-encoded Verified Name Certificate

A base64-encoded Verified Name (vname) certificate string is generated for you and is used for validation during WhatsApp Business API Client registration.

  1. Go to the Business Settings in the Facebook Business Manager.
  2. Select your WhatsApp Account from the WhatsApp Accounts list, if it isn't already.
  3. Under Manage People and Settings, select Settings.
  4. Click WhatsApp Manager.
  5. Under the Phone Numbers tab, you should see your phone numbers listed. Click Download for the phone number you want the vname certificate for.
    Download Certificate
  6. A pop-up dialog will display the vname certificate string in a gray box. Click Get Certificate.
    Download the Certificate String
  7. Use this vname certificate string in the cert parameter when registering with the account endpoint.

See the Verified Name (vname) documentation for more information.

Requesting a Registration Code

Submit your phone number and vname certificate base64-encoded string to request your registration code. You can request to receive your code over SMS or voice call.

Use the /v1/account endpoint to request your registration code.

POST /v1/account

{
    "cc": "your-country-code",
    "phone_number": "your- phone-number-without-country-code",
    "method": "sms" | "voice",
    "cert": "your-verified-name-cert-in-base64",
    "pin": "your-existing-6-digit-pin" # required if two-factor verification is enabled
}

Parameters

NameRequiredDescription

cc

Yes

Numerical country code for the phone number you are registering

phone_number

Yes

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

method

Yes

Method of receiving your registration code
Options: voice, sms

cert

Yes

Base64-encoded Verified Name certificate

pin

No

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

Response

Depending on the response received, the registration procedure can be considered complete or require another step to complete. If successful, you will receive one of the following HTTP status codes. Follow the instructions that match the response you received:

  • 201 Created — If the account already exists. You are already registered, so you do not need to do anything else.
  • 202 Accepted — If 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 verified name decoded from the cert parameter for you to confirm the right verified name is being set. If correct, proceed to the Registering Your Account section to complete registration.
{
  "account": [{
      "vname": "decoded-vname-from-cert"
  }]
}

If any errors are returned, refer to Error and Status Messages for more information.

Completing Your Account Registration

Once you have received the registration code via the method you specified above (SMS/voice), complete your account registration by sending an API call to the /v1/account/verify endpoint:

POST /v1/account/verify

{
  "code": "your-registration-code-received-by-sms-or-voice-call"
}

If successful, the response will return the HTTP status 201 Created with no payload object in response body.

If any errors are returned, refer to Error and Status Messages for more information.

If you are re-registering your account, the Coreapp needs to be restarted once registration is complete.