Authentication Templates
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:
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.
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 is significantly minimized.
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
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 Handshake and App Signing Key Hash.
Best Practices for Authentication Templates
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 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.
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.
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 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 to follow before you enable zero-tap authentication templates for WhatsApp business accounts
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.
Numbers registered before this date will still be supported, but should start planning a change of hosting type as soon as possible.
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
Sample request with components descriptions
Sample Copy Code Button Components Value
Sample One-tap Autofill Button Components Value
Sending Authentication Templates
POST
https://waba-v2.360dialog.io/messages
Request Body
Sample payload with Copy Code Button
Example Response
Upon success, the API will respond with a JSON object describing the newly created template.
[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.
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 start changing the hosting type of numbers to Cloud as soon as possible. Learn here how to integrate with Cloud API.
POST
https://waba.360dialog.io/v1/messages
Request Body
A successful response includes a messages
object with an id
.
Sample payload with Copy Code Button
Example Response
Upon success, the API will respond with a JSON object describing the newly created template.
Last updated