Verify a phone number

Two calls. We generate the code, deliver it over WhatsApp, and check it. You never store it.

  1. You start a verification

    msg.verify.start({ phone })

    We generate the code and deliver it over WhatsApp. You get a verificationId back.

  2. The user reads the code and types it in

    Into your own form. We are not involved until you check it.

  3. You check it

    msg.verify.check({ verificationId, code })

    approved means verified. You never stored the code.

Starting a verification

await msg.verify.start({
  phone: "+919812345678",   // E.164. Required.
  ttlSeconds: 300,          // how long the code stays valid
  codeLength: 6,
});

You get back a verificationId, a status of pending, and expiresAt.

On a test key the response also carries code — see Test keys and the sandbox.

Verifying a code

await msg.verify.check({ verificationId, code });

The five statuses

StatusMeaning
pendingCode sent, not yet checked.
approvedCorrect. The user is verified.
invalidWrong code. remainingAttempts tells you how many tries are left.
expiredPast expiresAt. Start a new verification.
max_attemptsToo many wrong guesses. Start a new verification.

A wrong code is not an error. It comes back as 200 with status: "invalid", because the request itself was perfectly valid. Only branch on status.

approved means the phone number is verified, not that anyone is logged in. Creating a session is yours — see Add WhatsApp OTP to your login.

Before you go live

Verify needs two things on your account that a test key does not check:

  1. An authentication template approved by Meta.
  2. An active sending number.

Missing either, a live key returns verify_not_configured. Both are set up in the console — see Connect your WhatsApp account.