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.
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.
Whatsapp Authentication-International Rates
Specific countries have an authentication-international rate in our whatsapp pricing. If you open an authentication conversation with a WhatsApp user whose country calling code is for a country that has an authentication-international rate, you will be billed that country’s authentication–international rate if:
- your business is eligible for authentication-international rates
- your business is based in another country (see Primary Business Location explained below)
- the conversation was opened on or after your start time for that country
For example, if your business is based in India and you open an authentication conversation with a WhatsApp user who has a +91 (India) country calling code, you will not be billed the authentication-international rate, since you are based in the same country as the user. If your business is based in Indonesia, however, you will be billed the authentication-international rate, if you meet all of the criteria above.
Eligibility
If your business opens more than 750K conversations in a moving 30-day period across all of your WhatsApp Business Accounts with WhatsApp users whose country calling codes are for a country that has an authentication-international rate, it will be deemed eligible for authentication-international rates.
Once deemed eligible, WhatsApp will set your start times 30 days out for each country that has an authentication-international rate. In addition, WhatsApp will attempt to determine your primary business location using publicly-available information.
WhatsApp will then send you an eligibility email that includes these start times and the country that WhatsApp set as your primary business location (if WhatsApp were able to determine the country). This provides you with 30 days notice before authentication-international rates apply.
Note that eligibility is permanent. Once your business is deemed eligible, all authentication conversations opened on or after your start time will be charged the authentication-international rate in markets where authorization-international rates apply.
Start Times
Start times are business- and country-specific timestamps. They indicate when newly-opened authentication conversations are subject to authentication-international rates. Authentication conversations opened by your business with WhatsApp users in these countries on or after these dates only will be charged authentication-international rates.
Start times are set when your business is first deemed eligible for authentication-international rates, and are 30 days from your eligibility date, so you will always have 30-days notice before the authentication-international rate applies.
Start times are included in your eligibility email.
Primary Business Location
Your primary business location is the country where your business is based. It will appear in the Business Manager under the Primary Business Location field starting May 1, 2024, if WhatsApp are able to determine where your business is based using publicly-available information.
Examples of publicly-available information include:
- Where your business may be publicly-traded and listed
- Your business’s corporate structure (where a parent or may be based or publicly-traded)
WhatsApp will attempt to determine where your business is based when:
- It is deemed eligible for authentication-international rates
- You edit your primary business location using the Business Manager.
This process can take up to 3 business days. The outcome of this determination can be:
- Verified — WhatsApp determined where your business is based and set your primary business location to this country.
- Need more information — WhatsApp require more information in order to make a determination.
- Rejected — WhatsApp disagreed with the country you designated in the Business Manager (if you used it to edit the Primary Business Location field)
You will be notified of the outcome in your initial eligibility email, or in a separate email if you used the Business Manager to edit your location.
If rejected or if WhatsApp need more information, or if you disagree with the country it determined to be the primary business location, you can use the Business Manager to edit your location.
Note that if your primary business location status is not verified but you are past your start time for a given country, any authentication conversation that you open with a WhatsApp user in that country will be billed the authentication-international rate.
Editing Your Primary Business Location
You can edit your business’s primary business location at any time using WhatsApp Business Manager:
Business Settings > Business info > Primary Business Location > Edit (button)
The Primary Business Location field in the Business Manager will also display a status:
- Verified — WhatsApp have verified your business’s primary location.
- Pending verification — WhatsApp in the process of determining your business’s primary location.
- Rejected — WhatsApp disagreed with the country you designated, based on publicly available information and what you included when you edited your location. You can manually edit your location again and include different information as part of your submission.
Examples
A business with an Indonesia primary business location opens an authentication conversation with a WhatsApp user:
| User location | Is business eligible? | Is on/after start time? | Rate billed |
|---|---|---|---|
| Indonesia | - | - | Authentication |
| India | No | - | Authentication |
| India | Yes | No | Authentication |
| India | Yes | Yes | Authentication-International |
A business with an India primary business location opens an authentication conversation with a WhatsApp user:
| User location | Is business eligible? | Is on/after start time? | Rate billed |
|---|---|---|---|
| India | - | - | Authentication |
| Indonesia | No | - | Authentication |
| Indonesia | Yes | No | Authentication |
| Indonesia | Yes | Yes | Authentication-International |
A business with a primary business location that does not have an authentication-international rate opens an authentication conversation with a WhatsApp user:
| User location | Is business eligible? | Is on/after start time? | Rate billed |
|---|---|---|---|
| Indonesia | No | - | Authentication |
| Indonesia | Yes | No | Authentication |
| Indonesia | Yes | Yes | Authentication-International |
| India | No | - | Authentication |
| India | Yes | No | Authentication |
| India | Yes | Yes | Authentication-International |