Client Documentation
Get StartedStatus Page
  • 360Dialog
    • Why you should use 360dialog as Business Solution Provider (BSP)
    • Prices, plans and payment options
  • client hub
    • 360Dialog Client Hub
    • Numbers
      • Manage your WABA
        • Account Statuses
    • Activity
    • Funds
      • Month Closing Invoice (MCI)
    • Payment Management
    • API Keys
    • Template Message Management
    • Partner Change
    • Cancellation
    • Downgrade
  • WhatsApp Marketing
    • Best practices to maintain Account Health and prevent being blocked
    • Driving users to your WhatsApp account
      • WhatsApp Channels
    • Business Search
    • Linking a WABA to a Facebook Page /EN
      • Vinculando uma conta WABA à uma página do Facebook /PT
      • Cómo vincular un WABA a una página de Facebook /ES
    • Linking a WABA to Google Message Ads
    • Ads that Click to WhatsApp (CTWA) /EN
      • Anúncios de Clique para o WhatsApp (CTWA) /PT
        • Como usar o WhatsApp para marketing e vendas? /PT
      • Anuncios que Click to WhatsApp (CTWA) /ES
        • ¿Cómo usar WhatsApp para marketing y ventas? /ES
    • Conversions API (CAPI)
    • Create Ads lookalike audience based on WhatsApp events
    • MM Lite API Beta
      • Onboarding
      • Sending Messages
  • waba basics
    • WhatsApp Business Platform
    • WhatsApp Accounts structure
    • WABA for Government Agencies
    • WABA Policy Enforcement
    • Architecture and Security
    • The Basics (Overview)
    • Webhook Events and Notifications
    • Messaging API
      • Messaging Health Status
      • Step to Step to move to Cloud API
        • [will be deprecated] WABA Integration (On-Premise)
    • Migrating Phone Numbers
      • Migrate number from Meta or alternate BSP to 360dialog Cloud API
      • Migrate a phone number to a new WABA
      • Migrate to alternate BSP
  • waba management
    • Creating new WABA
      • Using a new phone number
      • WhatsApp Coexistence
        • Coexistence Onboarding
        • Coexistence Webhooks
    • Display Name Guidelines
    • Meta Business Verification
    • Official Business Account (OBA) or blue badge
    • WABA Profile Info
    • Capacity, Quality Rating, and Messaging Limits
      • Accelerated Onboarding
    • Hosting type Change
  • waba Messaging
    • Sandbox (Test API Key)
    • Receiving messages
    • Before sending a message
      • Checklist for Message Broadcasts and Campaigns
    • Conversations
    • Messaging
    • Conversational Components
    • Media Messages
      • Upload, retrieve or delete media
    • Template Messages
      • Template Elements
      • Sending Template Messages
      • Authentication Templates
        • Zero-Tap Authentication Templates
        • One-Tap Autofill Authentication Templates
        • Copy Code Authentication Templates
      • Catalog Templates
      • Product Card Carousel Templates
      • Single-Product Message Templates
      • Coupon Code Templates
      • Limited-Time Offer Templates
      • Multi-Product Templates
    • Interactive Messages
      • Single and Multi Product Messages
      • Location Request Message
    • Flows
    • Products & Catalogs
    • Contacts and Location Messages
    • Payments (India Only)
      • Receive WhatsApp Payments via Payments Gateway
      • Receive WhatsApp Payments via Payment Links
      • Order Details Template Message
    • Payments (Singapore only)
      • Receive WhatsApp Payments via Stripe
  • Partners
    • Partner Documentation
  • Support
    • Help and Support
      • Opening Hours & Response Time
      • Status Pages
      • Meta Support
      • Common Issues
      • How to contact Support
    • Error Messages
    • Imprint & Data Privacy
    • FAQ
Powered by GitBook
On this page
  • Authentication Template Requirements
  • Buttons
  • Time-To-Live
  • Creating Authentication Templates
  • Sending Authentication Templates
  • [will be deprecated] If the number is registered on On-Premise API

Was this helpful?

  1. waba Messaging
  2. Template Messages

Authentication Templates

PreviousSending Template MessagesNextZero-Tap Authentication Templates

Last updated 11 months ago

Was this helpful?

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

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
Sample

Providing an authentication code to the user

  • "{{1}} is your verification code."

  • "{{1}} is your verification code. For your security, do not share this code."

  • "{{1}} is your verification code. This code expires in 15 minutes."

Authentication Template Requirements

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). The presets in the authentication message template fixed text are:

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

Buttons

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.

HandShake and App Signing Hash

Best Practices for Authentication Templates

  • Confirm the user's WhatsApp phone number before sending the one-time password or code to that number.

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

Time-To-Live

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.

By default, messages have a time-to-live of 24 hours (30 days for On-Premises API), but newly created authentication templates have a default time-to-live of 10 minutes.

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.

Existing templates created before this functionality was made available have a time-to-live of 24 hours (or 30 days for On-Premises API). 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 24 hours (or 30 days for On-Premises API).

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 may be a minor delay in the delivery of the failed message webhook, so you may wish to build in a small buffer when inferring a drop.

Best Practices for Authentication Templates

  • Confirm the user's WhatsApp phone number before sending the one-time password or code to that number.

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

Creating Authentication Templates

Use the create template endpoint and assemble the authentication components in the request:

The base-url should be https://waba-v2.360dialog.io for Cloud API and https://waba.360dialog.io for On-Premise.

If you are using On-Premise API, remember that it is being discontinued by Meta. No new signups will be allowed with this type of integration from May 15, 2024.

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

Use the create template endpoint and assemble the authentication components in the request:

POST /v1/configs/templates

Components

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

Placeholder
Description
Sample Value

<ADD_SECURITY_RECOMMENDATION>

Optional.

Boolean. Set to true if you want the template to include the string: For your security, do not share this code. Set to false to exclude the string.

true

<CODE_EXPIRATION_MINUTES>

Optional.

Integer. Indicates number of minutes the password or code is valid.

If omitted, the code expiration warning will not be displayed in the delivered message.

Minimum 1, maximum 90.

5

<OTP_TYPE>

Enum. Indicates button type. Set to COPY_CODE if you want the template to use a copy code button, or ONE_TAP to have it use a one-tap autofill button.

ONE_TAP

<TEXT>

String. Copy code button text.

Maximum 25 characters.

'Copy Code'

<AUTOFILL_TEXT>

One-tap buttons only.

String. One-tap button text.

Maximum 25 characters.

'Autofill'

<PACKAGE_NAME>

One-tap buttons only.

Your Android app's package name.

'com.example.myapplication'

<SIGNATURE_HASH>

One-tap buttons only.

'K8a%2FAINcGX7'

Sample request with components descriptions

    {
        "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

[
  {
    "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

[
  {
    "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

POST https://waba-v2.360dialog.io/messages

Request Body

Name
Type
Description

name

String

type

String

Message type

to

String

Recipient wa_id

messaging_product

String

Required only for Cloud API. Messaging service used for the request. Use "whatsapp".

components

String

language

String

{
    "messaging_product": "whatsapp",
    "contacts": [
        {
            "input": "12015553931",
            "wa_id": "12015553931"
        }
    ],
    "messages": [
        {
            "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI4Qzc5QkNGNTc5NTMyMDU5QzEA"
        }
    ]
}
Placeholder
Description
Sample Value

<CUSTOMER_PHONE_NUMBER>

The customer's WhatsApp phone number.

12015553931

<ONE-TIME PASSWORD>

The one-time password or verification code to be delivered to the customer.

Note that this value must appear twice in the payload.

J$FpnYnP

<TEMPLATE_LANGUAGE_CODE>

en_US

<TEMPLATE_NAME>

The template's name.

verification_code

Sample payload with Copy Code Button

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "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": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Copy Code"
        }
      ]
    }
  ]
}

Example Response

Upon success, the API will respond with a JSON object describing the newly created template.

{
    "id": "594425479261596",
    "status": "PENDING",
    "category": "AUTHENTICATION"
}

[will be deprecated] If the number is registered on On-Premise API

As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.

POST https://waba.360dialog.io/v1/messages

Request Body

Name
Type
Description

to

string

Recepient_wa_id

language

String

Contains a language object. Specifies the language the template may be rendered in.

The language object can contain the following fields:

policystring – Required. The language policy the message should follow. The only supported option is deterministic.

codestring – Required. The code of the language or locale to use.

Accepts both language andlanguage_locale formats (e.g., en and en_US).

name

String

Name of the template.

namespace

Namespace of the template.

components

String

A successful response includes a messages object with an id.

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}  

If a template is sent to an account that is incapable of receiving the authentication template, the 1026 (ReceiverIncapable) error will be sent in the error object to the configured Webhook server.

Sample payload with Copy Code Button

{
    "to": "recipient_wa_id",
    "type": "template",
    "template": {
        "namespace": "your-namespace",
        "name": "your-template-name",
        "language": {
            "code": "your-language-and-locale-code",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "user-otp-code"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "url",
                "index": 0,
                "parameters": [
                    {
                        "type": "text",
                        "text": "user-otp-code"
                    }
                ]
            }
        ]
    }
}

Example Response

Upon success, the API will respond with a JSON object describing the newly created template.

{
    "id": "594425479261596",
    "status": "PENDING",
    "category": "AUTHENTICATION"
}

URLs, media, and emojis are not supported. Because authentication templates with OTP buttons only consist of preset text and buttons, their risk of being is significantly minimized.

One-tap buttons are the preferred solution as they offer the best user experience. However, one-tap buttons are currently only supported on Android, requires changes to your application in order to perform a "handshake" with Meta, and your app's signing key hash. See Meta's Official documentation for and .

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 for additional tips.

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 for additional tips.

to follow before you enable zero-tap authentication templates for WhatsApp business accounts

Numbers registered before this date will still be supported, but should start planning a as soon as possible.

See above.

Note that even if your template is using a one-tap autofill button, this value must still be supplied. If Meta's unable to validate your the authentication template message will display a copy code button with this text instead.

Your app signing key hash. See Meta's Official documentation for .

The template's .

Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to of numbers to Cloud as soon as possible. .

See

Handshake
App Signing Key Hash
Template Messages
See more of Meta best practices
change of hosting type
start changing the hosting type
Learn here how to integrate with Cloud API
handshake
App Signing Key Hash
language and locale code
Buttons
Components
paused
Template Messages