Authentication Templates

If your mobile app offers users the option to receive one-time passwords or verification codes via WhatsApp, you must use an authentication template.

Authentication templates consist of:

• Fixed preset text: <VERIFICATION_CODE> is your verification code.
• An optional security disclaimer: For your security, do not share this code.
• An optional expiration warning: This code expires in <NUM_MINUTES> minutes.
• Either a one-tap autofill button, a copy code button, or no button at all if using zero-tap.

One-tap autofill buttons are the preferred solution as they offer the best user experience. However, one-tap autofill buttons are currently only supported on Android and require additional changes to your app's code.

See additional guidelines for when it's appropriate to use an authentication template.

Linked Device Security

Authentication templates now feature linked device security. This means that authentication messages are only delivered to a user's primary WhatsApp device.

Authentication messages that are sent to a user's linked devices are masked with a prompt instructing the user to view the message on their primary device.

This feature is enabled by default and does not require code changes. It cannot be configured or customized. Only available on Cloud API.

One-Tap Autofill Authentication Templates

Authentication templates include a one-tap autofill button.

When a WhatsApp user taps the autofill button, the WhatsApp client triggers an activity which opens your app and delivers it the password or code.

See One-Tap Autofill Authentication Templates to learn how to use them.

Copy Code Authentication Templates

Copy code authentication templates allow you to send a one-time password or code along with a copy code button to your users.

When a WhatsApp user taps the copy code button, the WhatsApp client copies the password or code to the device's clipboard. The user can then switch to your app and paste the password or code into your app.

See Copy Code Authentication Templates to learn how to use them.

Zero-Tap Authentication Templates

Zero-tap authentication templates allow your users to receive one-time passwords or codes via WhatsApp without having to leave your app.

When a user in your app requests a password or code and you deliver it using a zero-tap authentication template, the WhatsApp client broadcasts the included password or code, which your app can then capture with a broadcast receiver.

See Zero-Tap Authentication Templates to learn how to use them.

Best Practices

• Confirm the user's WhatsApp phone number before sending the one-time password or code to that number.
• Make it clear to your user that the password or code will be delivered to their WhatsApp phone number, especially if you offer multiple ways for the user to receive password or code delivery. See Getting Opt-In for additional tips.
• When the user pastes the password or code into your app, or your app receives it as part of the one-tap autofill button flow, make it clear to the user that your app has captured it.

See also Best Practices for Authenticating Users via WhatsApp.

Calculating Latency using Webhook Notifications

Multiple webhooks may be received upon confirmation of authentication template delivery to a WhatsApp end-user's linked device(s). Latency should be calculated based on the first webhook you receive indicating successful delivery to an end-user's primary device.

Example Message Lifecycle

1. The WhatsApp end-user is prompted for an authentication code
2. Your back-end performs the API call to send an authentication template
3. Cloud API attempts to send the message to end-user's primary device only
4. The end-user's primary device receives the message and confirms delivery
5. The first delivery webhook is sent to your back-end indicating successful primary device delivery sent to the WhatsApp end-user
   • In parallel, masked authentication messages are sent to each linked device
6. Subsequent delivery webhook(s) indicating linked device delivery sent to client upon confirmation from each linked device (assuming multiple, depending on the number of linked devices an end-user has)"

In the above scenario, you would calculate message latency based on the first delivery webhook you received in the lifecycle.

Customizing Time-To-Live

See Customizing Time-To-Live.

Sending Authentication Template Messages

Use Cloud API or On-Premises API to send approved authentication templates in a template message.

• Sending authentication template messages with Cloud API
• Sending authentication template messages with On-Premises API

Template Previews

You can generate previews of authentication template text in various languages that include or exclude the security recommendation string and code expiration string using the GET /<WABA_ID>/message_template_previews endpoint.

Request Syntax

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_template_previews
  ?category=AUTHENTICATION,
  &language=<LANGUAGE>, // Optional
  &add_security_recommendation=<ADD_SECURITY_RECOMMENDATION>, // Optional
  &code_expiration_minutes=<CODE_EXPIRATION_MINUTES>, // Optional
  &button_types=<BUTTON_TYPES> // Optional

Query String Parameters

Example Request

curl 'https://graph.facebook.com/v17.0/102290129340398/message_template_previews?category=AUTHENTICATION&languages=en_US,es_ES&add_security_recommendation=true&code_expiration_minutes=10&button_types=OTP' \
-H 'Authorization: Bearer EAAJB...'

Example Response

{
  "data": [
    {
      "body": "*{{1}}* is your verification code. For your security, do not share this code.",
      "buttons": [
        {
          "autofill_text": "Autofill",
          "text": "Copy code"
        }
      ],
      "footer": "This code expires in 10 minutes.",
      "language": "en_US"
    },
    {
      "body": "Tu código de verificación es *{{1}}*. Por tu seguridad, no lo compartas.",
      "buttons": [
        {
          "autofill_text": "Autocompletar",
          "text": "Copiar código"
        }
      ],
      "footer": "Este código caduca en 10 minutos.",
      "language": "es_ES"
    }
  ]
}

Bulk Management

Use the POST /<WABA_ID>/upsert_message_templates endpoint to bulk update or create authentication templates in multiple languages that include or exclude the optional security and expiration warnings.

If a template already exists with a matching name and language, the template will be updated with the contents of the request, otherwise, a new template will be created.

Request Syntax

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

Post Body

{
  "name": "<NAME>",
  "languages": [<LANGUAGES>],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": <ADD_SECURITY_RECOMMENDATION> // Optional
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": <CODE_EXPIRATION_MINUTES> // Optional
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "<OTP_TYPE>",
          "supported_apps": [
            {
              "package_name": "<PACKAGE_NAME>", // One-tap and zero-tap buttons only
              "signature_hash": "<SIGNATURE_HASH>" // One-tap and zero-tap buttons only
            }
          ]
        }
      ]
    }
  ]
}

Properties

All template creation properties are supported, with these exceptions:

• The language property is not supported. Instead, use languages and set its value to an array of language and locale code strings. For example: ["en_US","es_ES","fr"].
• The text property is not supported.
• The autofill_text property is not supported.

Example Copy Code Request

This example creates three authentication templates in English, Spanish, and French, with copy code buttons. Each template is named "authentication_code_copy_code_button" and includes the security recommendation and expiration time.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_copy_code_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 10
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE"
        }
      ]
    }
  ]
}'

Example One-Tap Autofill Request

This example (1) updates an existing template with the name "authentication_code_autofill_button" and language "en_US", and (2) creates two new authentication templates in Spanish and French with one-tap autofill buttons. Both newly created templates are named "authentication_code_autofill_button" and include the security recommendation and expiration time.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_autofill_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 15
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "supported_apps": [
            {
              "package_name": "com.example.luckyshrub",
              "signature_hash": "K8a/AINcGX7"
            }
          ]
        }
      ]
    }
  ]
}'

Example Response

{
  "data": [
    {
      "id": "954638012257287",
      "status": "APPROVED",
      "language": "en_US"
    },
    {
      "id": "969725527415202",
      "status": "APPROVED",
      "language": "es_ES"
    },
    {
      "id": "969725530748535",
      "status": "APPROVED",
      "language": "fr"
    }
  ]
}

Sample App

See our WhatsApp One-Time Password (OTP) Sample App for Android on Github. The sample app demonstrates how to send and receive OTP passwords and codes via the API, how to integrate the one-tap autofill and copy code buttons, how to create a template, and how to spin up a sample server.

See Also

• Official Business Account — You may wish to request Official Business Account status to build trust with your users, which will reduce the likelihood that they dismiss or ignore your messages.
• Webhooks for read receipts — We recommend that you subscribe to the messages webhooks field so you can be notified when a user receives and reads your authentication template with an OTP button. See Webhooks for Cloud API or Webhooks for On-Premises API.