WhatsApp Business Management API

Authentication Templates

Authentication templates will be available in India on July 1, 2024.

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.

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.

Time-To-Live

If we are unable to deliver a message to a WhatsApp user, we will continue attempting to deliver the message for a period of time known as a time-to-live.

By default, messages have a time-to-live of 30 days, but newly created authentication templates have a default time-to-live of 10 minutes.

If we are unable to deliver an authentication template for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message. If the time between your authentication template message send request exceeds the time-to-live and you receive no webhook, assume it was dropped.

To override the default time-to-live when creating an authentication template, include the message_send_ttl_seconds property with a value set between 60 and 600 seconds.

Existing templates created before this functionality was made available have a time-to-live of 30 days. If you wish, you can edit an existing template and override its time-to-live by setting its message_send_ttl_seconds property.

You can also set an authentication template's message_send_ttl_seconds property to -1. This will set its time-to-live to 30 days.

We encourage you to set a time-to-live for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable.

Note that there could be a minor delay in delivery of the failed message webhook, so you may wish to build in a small buffer when inferring a drop.

Sending Authentication Template Messages

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

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 WhatsApp Business Account > 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

PlaceholderDescriptionExample Value

<LANGUAGE>

Comma-separated list

Optional.


Comma-separated list of language and locale codes of language versions you want returned.


If omitted, versions of all supported languages will be returned.

en_US,es_ES

<ADD_SECURITY_RECOMMENDATION>

Boolean

Optional.


Set to true if you want the security recommendation body string included in the response.


If omitted, the security recommendation string will not be included.

true

<CODE_EXPIRATION_MINUTES>

Int64

Optional.


Set to an integer if you want the code expiration footer string included in the response.


If omitted, the code expiration footer string will not be included.


Value indicates number of minutes until code expires.

Minimum 1, maximum 90.

10

<BUTTON_TYPES>

Comma-separated list of strings

Required.


Comma-separated list of strings indicating button type.


If included, the response will include the button text for each button in the response.


For authentication templates, this value must be OTP.

OTP

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 WhatsApp Business Account > 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>",
          "package_name": "<PACKAGE_NAME>", // One-tap buttons only
          "signature_hash": "SIGNATURE_HASH>", // One-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",
          "package_name": "com.example.luckyshrub",
          "signature_hash": "K8a%2FAINcGX7"
        }
      ]
    }
  ]
}'

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