← Back to How-To Guides

How to Register a Phone Number to Use with the Official WhatsApp API and Set a Two-Step PIN

Adding a number to a WhatsApp account is not the same as making it usable on the API. That last step is called registration, and it needs a six-digit PIN. Most people never do it themselves, because their provider does. It matters when something goes wrong, or when you move to another provider.

What registration is

  • A number can sit in your WhatsApp account and still not be usable on the Cloud API. Until it is registered, sends fail with "Account not registered" (error 133010).
  • Registration is one API call, made with a six-digit PIN. The PIN becomes the number's two-step verification PIN. Your onboarding provider may do the registration at the end of the signup, so ask them whether they do, and whether they will need the PIN if you or a previous provider already set one. If you'd rather not deal with a PIN, you can turn two-step verification off in WhatsApp Manager first.
  • Registration comes after verification, which proves you control the number with a one-time code sent by SMS or voice call. While onboarding via a Service Provider, the signup works out whether the number needs verification or is already verified, and shows the code step only when it's needed. So as the number's owner you usually don't need to worry about verifying or registering it yourself when you onboard through a Tech Provider or Solution Partner.

Who registers the number, and when

  • A standard-onboarding (API-only) provider registers the number at the end of onboarding. The signup only creates the assets and hands the provider the IDs. The provider's own backend then calls register with a PIN. If it's a number that was deregistered earlier (a move), it needs the existing PIN, or any six digits if two-step verification is off.
  • A coexistence provider does not need to. Connecting the number to the WhatsApp Business app already registers it, so the provider skips the step and never asks for a PIN.
  • If you onboard the number yourself (you add it in WhatsApp Manager or your business portfolio, without a provider): verifying the number adds it to your account, but Meta's pages don't say that this also registers it. Assume it doesn't. Check the status below, and if it isn't CONNECTED, call register yourself with a PIN of your choice. Without it, sends fail with "Account not registered" (133010).

The two Meta calls for debugging

Both use the number's phone number ID (not the phone number itself) and an access token for it. If a provider onboarded the number for you, you don't have that token, so ask the provider to run these and send you the result.

CHECK REGISTRATION STATUS

curl 'https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>?fields=status' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

{ "status": "CONNECTED", "id": "<PHONE_NUMBER_ID>" }

A number must have the status CONNECTED to send and receive messages. You can also add code_verification_status to the fields to see whether the number has been verified.

REGISTER THE NUMBER

curl -X POST 'https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/register' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "messaging_product": "whatsapp", "pin": "<6-DIGIT PIN>" }'

{ "success": true }

Meta allows 10 registration requests per number in 72 hours, so don't loop on this call (error 133016).

If you use Watobot

Watobot holds your token for you, encrypted under your Watobot API key, so you never have to handle it. Both calls above are available for your numbers with just your Watobot API key: one to check the registration status and one to register the number with a PIN you choose. That makes it easy to see where a number stands, and to move it into or out of Watobot without asking anyone else for a token.

The two-step verification PIN

  • Who sets it: whoever registers the number, usually your provider. Ask them for it, and keep it somewhere safe.
  • What needs it: the next provider needs it when it registers the number, and Meta asks for it to change or delete the number.
  • Being phased out: Meta is deprecating the PIN for eligible Cloud API numbers.
  • Changing it, turning it off, or losing it: see the two-step PIN section of the de-register guide.

Errors you may see

  • 133010, "Account not registered": registration didn't happen or didn't finish. The provider has to call register. If it's a coexistence number, it shouldn't need to, so check it's still connected in the Business app.
  • 133016, too many attempts: Meta allows 10 registration requests per number in 72 hours. Stop, wait, then retry once with the right PIN. Every wrong PIN counts toward the limit.
  • A wrong PIN: the number already has a PIN and the one sent doesn't match. Get the right one from the previous provider, or see what to do if it is lost.
  • "This number is registered to an existing WhatsApp account": the signup tried to add the number as a brand-new one, and it's already on WhatsApp. See the move guide.

Meta's own docs

Related guides