Authentication Templates (One-Time Passwords)

If you want to send customers a one-time password (OTP) or verification code on WhatsApp, for a login, signup, password reset or payment check, you must use an authentication template. Meta says only authentication templates can send a one-time passcode for identity verification. Marketing and utility templates cannot.

Authentication templates are the most restricted category. You don't write the message text yourself. WhatsApp uses a fixed sentence, and you choose a few options:

• Fixed text (not customizable): "123456 is your verification code." (with your code in place of 123456)
• Optional security disclaimer: "For your security, do not share this code."
• Optional expiry warning: "This code expires in 10 minutes." (you choose the number, from 1 to 90 minutes)
• A button: a copy code button, a one-tap autofill button, or no visible button when you use zero-tap.

Choosing how the code reaches your app#

Meta calls one-tap autofill the preferred option on Android, because the customer never has to leave your app. On a non-Android device, a one-tap or zero-tap template shows a copy code button instead, so the code always gets through.

Security built into authentication templates#

• Primary device only: authentication messages are delivered only to the user's primary WhatsApp device. On linked devices (such as WhatsApp Web or desktop) the message is masked with a prompt to view it on the primary device. This is on by default, can't be turned off, and is available only on Cloud API.
• No forwarding: WhatsApp disables forwarding of authentication messages, to fight phishing.
• Content restrictions: URLs, media and emojis are not allowed in authentication template content or parameters, and parameters are limited to 15 characters.

Best practices from Meta#

1. 1

   Get opt-in and let the user choose WhatsApp

   You need opt-in before messaging someone. A common approach is to offer a choice of channels (WhatsApp, SMS, email). Make it clear the code will arrive on their WhatsApp number. See Opt-in rules.

2. 2

   Confirm their WhatsApp number

   Ask the user to confirm the number before sending. People may use a different number for WhatsApp than for SMS (for example, travellers with two SIM cards). If many codes are undeliverable, users may be picking WhatsApp without being registered on it. On Android you can check that WhatsApp is installed before offering it.

3. 3

   Set a short time-to-live

   Set the template's time-to-live to no more than your code's expiry time, so nobody receives a code that has already expired (see Time-to-live below).

4. 4

   Tell the user the code was received

   When the user pastes the code, or your app receives it through one-tap or zero-tap, show them clearly that your app has it.

5. 5

   Be careful with account recovery

   WhatsApp only verifies phone-number ownership at registration, and numbers get recycled. For sensitive flows such as account recovery, where the WhatsApp code may be the only check, verify the WhatsApp account first (for example with an initial OTP while the user is logged in) or add an extra challenge.

Technical details#

Create a copy code template#

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates with "category": "authentication". You don't send body text, because the text is fixed:

{
  "name": "authentication_code_copy_code_button",
  "language": "en_US",
  "category": "authentication",
  "message_send_ttl_seconds": 60,
  "components": [
    { "type": "body", "add_security_recommendation": true },
    { "type": "footer", "code_expiration_minutes": 5 },
    {
      "type": "buttons",
      "buttons": [
        { "type": "otp", "otp_type": "copy_code", "text": "Copy Code" }
      ]
    }
  ]
}

You create the button with "type": "otp", but WhatsApp stores it as a url button. You'll see URL when you read the template back.

One-tap autofill and zero-tap (Android)#

These need your Android app details on the button:

{
  "type": "otp",
  "otp_type": "one_tap",
  "text": "Copy Code",
  "autofill_text": "Autofill",
  "supported_apps": [
    { "package_name": "com.example.luckyshrub", "signature_hash": "K8a/AINcGX7" }
  ]
}

• supported_apps takes up to 5 package name + signing key hash pairs (for different app builds). The signature hash is exactly 11 characters.
• For zero-tap, use "otp_type": "zero_tap" and add "zero_tap_terms_accepted": true. If it is false, the template is not created. Zero-tap templates still define the one-tap and copy code labels, because they are shown if the automatic delivery fails.
• Handshake: before calling the API, your app must tell the WhatsApp client to expect a code. If there's no handshake, or the message fails WhatsApp's eligibility checks (for example, the handshake is older than 10 minutes or than code_expiration_minutes, or the package name or signing hash doesn't match), the message shows a copy code button instead.
• If you set no code_expiration_minutes, a one-tap button is disabled 10 minutes after the message is sent. Otherwise it is disabled after the number of minutes you set.

Meta's OTP Android SDK and sample app cover the handshake and receiver code.

Send the code#

POST /<PHONE_NUMBER_ID>/messages. The code goes in twice: once as the body parameter and once as the button parameter. Maximum 15 characters.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12015553931",
  "type": "template",
  "template": {
    "name": "verification_code",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [ { "type": "text", "text": "J$FpnYnP" } ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [ { "type": "text", "text": "J$FpnYnP" } ]
      }
    ]
  }
}

Time-to-live#

If WhatsApp can't deliver a message right away, it keeps trying for the template's time-to-live (TTL), then drops it.

If you get no delivered status webhook before the TTL runs out, assume the message was dropped.

Creating many languages at once#

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates creates or updates the same authentication template in several languages in one call. Use "languages": ["en_US","es_ES","fr"] instead of language. An existing template with the same name and language is updated, and the others are created.

"I didn't request a code" button#

Meta is rolling out an "I didn't request a code" button to businesses gradually (beta). When a user taps it, you receive a messages webhook of type: "button" with payload: "DID_NOT_REQUEST_CODE".

Frequently asked#

Gotchas & common mistakes#