# Authentication Templates

{% hint style="info" %}
Starting April 1, 2024, any existing authentication template that is not an [authentication template with a one-time password button ](#authentication-template-requirements)cannot be sent, edited, or appealed. \
\
Authentication templates are available in India since July 1, 2024.
{% endhint %}

Authentication templates enables businesses to authenticate users with one-time passcodes (usually 4-8 digit alphanumeric codes), potentially at multiple steps in the login process (e.g., account verification, account recovery, integrity challenges).

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

It's appropriate to use an authentication template when:

| Definition                                   | Examples                                                                                                                                                                                                               |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Providing an authentication code to the user | <ul><li>"{{1}} is your verification code."</li><li>"{{1}} is your verification code. For your security, do not share this code."</li><li>"{{1}} is your verification code. This code expires in 15 minutes."</li></ul> |

## Authentication Template Requirements

To access Authentication Message templates, businesses must satisfy the following two requirements:

1. [Complete a Scaling Path](https://docs.360dialog.com/docs/waba-management/meta-business-verification): business need to successfully complete one of Meta’s scaling paths, such as Meta Business Verification or Partner-led Business Verification.
2. [Messaging Limit](https://docs.360dialog.com/docs/waba-management/capacity-quality-rating-and-messaging-limits#default-limit): phone number must have a minimum daily messaging limit of 2,000 business-initiated conversations.

#### Formatting

Authentication templates include optional add-ons like security disclaimers and expiry warnings. In addition, authentication templates must have a one-time password button (copy code or one-tap).&#x20;

It 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.

<figure><img src="/files/JBQ8v7jdlRL6qpNYP6vb" alt=""><figcaption></figcaption></figure>

URLs, media, and emojis are not supported. Because authentication templates with OTP buttons only consist of preset text and buttons, their risk of being [paused ](/partner/messaging/template-messages.md#template-pausing)is significantly minimized.

### Linked Device Security <a href="#linked-device-security" id="linked-device-security"></a>

{% hint style="info" %}
This feature is enabled by default by Meta and does not require code changes. It cannot be configured or customized. It is only available on Cloud API.
{% endhint %}

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

<img src="https://scontent.flis10-1.fna.fbcdn.net/v/t39.2365-6/458481136_1204876024064039_8216873060873003926_n.png?stp=dst-webp&#x26;_nc_cat=100&#x26;ccb=1-7&#x26;_nc_sid=e280be&#x26;_nc_ohc=7C_m9_qbe6QQ7kNvgECyNqn&#x26;_nc_zt=14&#x26;_nc_ht=scontent.flis10-1.fna&#x26;_nc_gid=AIWkYG3FLq1hKdvSa3JlN4o&#x26;oh=00_AYAMksGSDdABdr8hOg_LsyHIp1tibpgoLnbRwRGFDO_NDw&#x26;oe=6729E126" alt="" width="325">

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.

## Buttons <a href="#buttons" id="buttons"></a>

Authentication templates must include either a copy code or one-tap autofill button. Buttons behave differently when tapped by a user:

* A **copy code** button copies the one-time password or code to the user's clipboard. The user can then manually switch to your app and paste the password or code into your app's interface.
* A **one-tap autofill** button automatically loads and passes your app the one-time password or code.&#x20;
* Zero Tap Authentication Templates allow your users to receive one-time passwords or codes via WhatsApp without having to leave your app. See See [Zero-Tap Authentication Templates](/partner/messaging/template-messages/authentication-templates/zero-tap-authentication-templates.md) to learn how to use them.

#### **HandShake and App Signing Hash**

Authentication Templates requires changes to your application in order to perform a "handshake" with Meta, and your app's signing key hash.&#x20;

See Meta's Official documentation for [Handshake](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#handshake) and [App Signing Key Hash](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#app-signing-key-hash).

## Time-To-Live <a href="#time-to-live" id="time-to-live"></a>

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

If Meta is unable to deliver an authentication template for an amount of time that exceeds its time-to-live, they 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.

See [Customizing Time-To-Live](/partner/messaging/template-messages.md#customizing-time-to-live).

#### Best Practices for Authentication Templates <a href="#best-practices" id="best-practices"></a>

* 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 [Template Messages](/partner/messaging/template-messages.md#best-practices-to-get-your-template-message-approved) 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 more of Meta best practices ](https://www.facebook.com/business/help/285737223876109)to follow before you enable zero-tap authentication templates for WhatsApp business accounts&#x20;

## Creating Authentication Templates

You can use the Partner API to create authentication templates. Alternatively, you can also create it using the 360dialog Hub.&#x20;

#### In the API

Use the create template [endpoint](https://docs.360dialog.com/docs/messaging-api/api-reference/templates#post-v1-configs-templates) and assemble the authentication components in the request:

The message template name field is limited to 512 characters. The message template content field is limited to 1024 characters.

#### Headers

| Name         | Type   | Description |
| ------------ | ------ | ----------- |
| D360-API-KEY | string |             |

#### Request Body

<table><thead><tr><th>Name</th><th width="199">Type</th><th>Description</th></tr></thead><tbody><tr><td>name<mark style="color:red;">*</mark></td><td>string</td><td></td></tr><tr><td>components<mark style="color:red;">*</mark></td><td>array[objects]</td><td>Array of objects that describe the components that make up the template. </td></tr><tr><td>category<mark style="color:red;">*</mark></td><td>string</td><td>Allowed values: <strong><code>AUTHENTICATION</code></strong></td></tr><tr><td>language<mark style="color:red;">*</mark></td><td>string</td><td><a href="https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages">View list of supported languages here.</a></td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}
Upon success, the API will respond with a JSON object describing the newly created template.

```javascript
```

{% endtab %}
{% endtabs %}

#### Components <a href="#components" id="components"></a>

The `components` value in the request must be an array of objects that describes each component that makes up the template. Authentication templates must have the following components:

* a single **body** component
* a single **footer** component
* a single **OTP Button** component

#### Properties <a href="#properties" id="properties"></a>

| Placeholder                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Sample Value                  |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| `<ADD_SECURITY_RECOMMENDATION>` | <p><strong>Optional.</strong></p><p></p><p>Boolean. Set to <code>true</code> if you want the template to include the string: <em><strong>For your security, do not share this code.</strong></em> Set to <code>false</code> to exclude the string.</p>                                                                                                                                                                                                                         | `true`                        |
| `<CODE_EXPIRATION_MINUTES>`     | <p><strong>Optional.</strong></p><p></p><p>Integer. Indicates number of minutes the password or code is valid.</p><p></p><p><strong>If omitted, the code expiration warning will not be displayed in the delivered message.</strong><br></p><p>Minimum 1, maximum 90.</p>                                                                                                                                                                                                      | `5`                           |
| `<OTP_TYPE>`                    | <p>Enum. Indicates button type. Set to <code>COPY\_CODE</code> if you want the template to use a copy code button, or <code>ONE\_TAP</code> to have it use a one-tap autofill button.</p><p></p><p>See <a href="#buttons">Buttons</a> above.</p>                                                                                                                                                                                                                               | `ONE_TAP`                     |
| `<TEXT>`                        | <p>String. Copy code button text.</p><p><br></p><p><strong>Note that even if your template is using a one-tap autofill button, this value must still be supplied.</strong> If Meta's unable to validate your <a href="https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#handshake">handshake</a> the authentication template message will display a copy code button with this text instead.<br></p><p>Maximum 25 characters.</p> | `'Copy Code'`                 |
| `<AUTOFILL_TEXT>`               | <p><strong>One-tap buttons only.</strong></p><p></p><p>String. One-tap button text.<br></p><p>Maximum 25 characters.</p>                                                                                                                                                                                                                                                                                                                                                       | `'Autofill'`                  |
| `<PACKAGE_NAME>`                | <p><strong>One-tap buttons only.</strong></p><p></p><p>Your Android app's package name.</p>                                                                                                                                                                                                                                                                                                                                                                                    | `'com.example.myapplication'` |
| `<SIGNATURE_HASH>`              | <p><strong>One-tap buttons only.</strong></p><p></p><p>Your app signing key hash. See Meta's Official documentation for <a href="https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#app-signing-key-hash">App Signing Key Hash</a>.</p>                                                                                                                                                                                            | `'K8a%2FAINcGX7'`             |

**Sample request with components descriptions**

```json
    {
        "name": "sample",
        "language": "es_ES",
        "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>",
                "text": "<TEXT>",
                "autofill_text": "<AUTOFILL_TEXT>", /*One-tap buttons only*/
                "package_name": "<PACKAGE_NAME>", /*One-tap buttons only*/
                "signature_hash": "<SIGNATURE_HASH>" /*#One-tap buttons only*/
                    }
                ]
            }
        ],
    }
```

**Sample Copy Code Button Components Value**

```json
[
  {
    "type": "BODY", 
    "add_security_recommendation": true
  }, 
  {
    "type": "FOOTER", 
    "code_expiration_minutes": 5
  },
  { 
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "OTP",
        "otp_type": "COPY_CODE",
        "text": "Copy Code"
      }
    ]
  }
]
```

**Sample One-tap Autofill Button Components Value**

```json
[
  {
    "type": "BODY", 
    "add_security_recommendation": true
  }, 
  {
    "type": "FOOTER", 
    "code_expiration_minutes": 5
  },
  { 
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "OTP",
        "otp_type": "ONE_TAP",
        "text": "Copy Code",
        "autofill_text": "Autofill",
        "package_name": "com.example.myapplication",
        "signature_hash": "K8a%2FAINcGX7"
      }
    ]
  }
]
```

## Sending Authentication Templates&#x20;

Please use this [endpoint](https://docs.360dialog.com/docs/messaging-api/api-reference/messages#post-messages).

#### Request Body

| Name               | Type   | Description                                                                                                                                |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| name               | String | Name of the template.                                                                                                                      |
| type               | String | Message type                                                                                                                               |
| to                 | String | Recipient wa\_id                                                                                                                           |
| messaging\_product | String | <p><strong>Required only for Cloud API.</strong><br>Messaging service used for the request. Use <code>"whatsapp"</code>.</p>               |
| components         | String | See [Components](#components)                                                                                                              |
| language           | String | [View list of supported languages here.](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) |

{% tabs %}
{% tab title="201: Created " %}

```json
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="318">Placeholder</th><th>Description</th><th>Sample Value</th></tr></thead><tbody><tr><td><code>&#x3C;CUSTOMER_PHONE_NUMBER></code></td><td>The customer's WhatsApp phone number.</td><td><code>12015553931</code></td></tr><tr><td><code>&#x3C;ONE-TIME PASSWORD></code></td><td><p>The one-time password or verification code to be delivered to the customer.<br></p><p>Note that this value must appear twice in the payload.</p></td><td><code>J$FpnYnP</code></td></tr><tr><td><code>&#x3C;TEMPLATE_LANGUAGE_CODE></code></td><td>The template's <a href="https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/supported-languages">language and locale code</a>.</td><td><code>en_US</code></td></tr><tr><td><code>&#x3C;TEMPLATE_NAME></code></td><td>The template's name.</td><td><code>verification_code</code></td></tr></tbody></table>

**Sample payload with Copy Code Button**

```json
{
  "messaging_product": "whatsapp",
  "to": "<CUSTOMER_PHONE_NUMBER>",
  "type": "template",
  "template": {
    "name": "<TEMPLATE_NAME>",
    "language": {
      "code": "<TEMPLATE_LANGUAGE_CODE>"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "<ONE-TIME PASSWORD>"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [
          {
            "type": "text",
            "text": "COPY_CODE"
          }
        ]
      }
    ]
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.360dialog.com/partner/messaging/template-messages/authentication-templates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.