ChatApp Message Service:Best practices for authentication templates

Background information

On May 1, 2023, WhatsApp launched an authentication template that contains a one-time password (OTP) button. Starting from May 29, 2023, all new authentication templates must contain an OTP button. For more information about WhatsApp authentication templates, see WhatsApp message templates.

Authentication template

Composition

An authentication template with an OTP button consists of the following content:

• Preset text:

  • <VERIFICATION_CODE> is your verification code.

  • Security disclaimer (optional): For your security, do not share this code.

  • Expiration warning (optional): This code expires in <NUM_MINUTES> minutes.

• Button: a copy code or a one-tap autofill button

Example:

Limits

• An authentication template with an OTP button consists of only preset text and a button.

• URLs, media resources, and emojis cannot be specified as the content or parameters of authentication templates.

• The verification code of an authentication template can be up to 15 characters in length.

Buttons

An authentication template must contain a copy code button or a one-tap autofill button. The buttons work differently when they are tapped by users.

• Copy code button: A user taps this button to copy the OTP or verification code to the clipboard. Then, the user switches to your app and pastes the OTP or verification code into the app interface.

• One-tap autofill button: After a user taps this button, your app is automatically loaded and the OTP or verification code is passed to the app.

We recommend that you use the one-tap autofill button because it provides the optimal user experience. Only Android supports the one-tap autofill button. In addition, if you want to use the one-tap autofill button, you must change the app code to perform a handshake and change the signing key hash of the app. For more information, see the Handshake and App signing key hash sections in this topic.

Best practices

• Confirm the WhatsApp phone numbers before you send out OTPs or verification codes.

• Make it clear to users that OTPs or verification codes will be delivered to their WhatsApp phone numbers, especially if you provide users with multiple options to receive OTPs or verification codes.

• If users paste OTPs or verification codes into your app, or your app receives OTPs or verification codes passed by one-tap autofill buttons, make it clear to users that your app has received the passwords or codes.

Parameters

App signing key hash

If you are creating an authentication template that uses a one-tap autofill button, you must include your app signing key hash in the components array.

To calculate your hash, follow the instructions provided by Google in Computing your app's hash string.

If you download your app signing key certificate as instructed by Google, you can use the certificate together with the sms_retriever_hash_v9.sh shell script to calculate the hash.

Handshake

If a user of your app requests an OTP or verification code and chooses to deliver the OTP or the verification code to the WhatsApp phone number, you need to perform a handshake and call our API to send an authentication template message. After the WhatsApp app or WhatsApp Business app receives the message, the WhatsApp app will check whether the message is eligible. If the message passes the eligibility check, the WhatsApp app will start the intent and display the message to the user. When the user taps the one-tap autofill button in the message, the WhatsApp app loads your app and passes a password or verification code to your app.

Eligibility checks

After the WhatsApp app or WhatsApp Business app receives an authentication template message, the app checks the items that are described in the following section. If one of the checks fails, the one-tap autofill button will be replaced with a copy code button.

• The handshake is initiated within 10 minutes before the message is sent.

• The app package name contained in the message matches the app package name set on the intent. The app package name contained in the message is the value of package_name in the components array that is set when you create the authentication template. The WhatsApp app or WhatsApp Business app determines whether the app package names match by using the getCreatorPackage method called in the PendingIntent object provided by your app.

• The app signing key hash in the message matches the signing key hash of your app. The app signing key hash in the message is the value of signature_hash in the components array that is set when you create the authentication template.

• The message contains the text of the one-tap autofill button.

• Your app has defined an activity to receive the password or the verification code. For more information, see the Activity section in this topic.

Android notifications

An Android notification that indicates that a user has received a WhatsApp authentication template message will appear on the Android device of the user only in the following situations:

• The user logs on to the WhatsApp app or the WhatsApp Business app with the phone number or the account that receives the message.

• The user logs on to your app.

• The Android operating system is KitKat (4.4, API 19) or later.

• Show notifications is enabled under Settings > Notifications in the WhatsApp app or WhatsApp Business app.

• Device-level notification is enabled for the WhatsApp app or WhatsApp Business app.

• Previous messages in the WhatsApp app or WhatsApp Business app between the user and your enterprise are not muted.

Client implementation

The following section describes how to implement an activity and class in your app.

Activity

Declare an activity and intent filter that can receive the OTP or verification code. The intent filter must contain the action name com.whatsapp.otp.OTP_RETRIEVED.

The WhatsApp app or WhatsApp Business app will immediately initiate the activity after the authentication template message is received and the message passes all eligibility checks.

Public class

Define the activity public class that can accept the OTP or the verification code that is passed to your app.

Initiate a handshake

The following example demonstrates how to initiate a handshake by using the WhatsApp app or the WhatsApp Business app.

public void sendOtpIntentToWhatsApp() {
   // Send OTP_REQUESTED intent to both WA and WA Business App
   sendOtpIntentToWhatsApp("com.whatsapp");
   sendOtpIntentToWhatsApp("com.whatsapp.w4b");
}

private void sendOtpIntentToWhatsApp(String packageName) {

  /**
  * Starting with Build.VERSION_CODES.S, it will be required to explicitly 
  * specify the mutability of  PendingIntents on creation with either 
  * (@link #FLAG_IMMUTABLE} or FLAG_MUTABLE
  */
  int flags = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ? FLAG_IMMUTABLE : 0;
  PendingIntent pi = PendingIntent.getActivity(
      getApplicationContext(), 
      0, 
      new Intent(), 
      flags);


  // Send OTP_REQUESTED intent to WhatsApp
  Intent intentToWhatsApp = new Intent();
  intentToWhatsApp.setPackage(packageName);
  intentToWhatsApp.setAction("com.whatsapp.otp.OTP_REQUESTED");
  // WA will use this to verify the identity of the caller app.
  Bundle extras = intentToWhatsApp.getExtras();
  if (extras == null) {
     extras = new Bundle();
  }
  extras.putParcelable("_ci_", pi);
  intentToWhatsApp.putExtras(extras);
  getApplicationContext().sendBroadcast(intentToWhatsApp);
}

Error signals

If your message fails an eligibility check, the one-tap autofill button will be replaced with a copy code button. In addition, message notifications may be blocked by the device, WhatsApp app, or WhatsApp Business app. To help debugging, the WhatsApp app or WhatsApp Business app displays some error information by using the com.whatsapp.OTP_ERROR intent. In this case, you will receive an error key and message instead of a one-time password or verification code.

Some error signals are displayed only if you run the WhatsApp app or the WhatsApp Business app in the Android emulator.

Integration

Error signals are delivered by using broadcasted intent. Therefore, you must implement BroadcastReceiver to receive error signals.

In manifest.xml

<receiver
 android:name=".app.otp.OtpErrorReceiver"
 android:enabled="true"
 android:exported="true" >
   <intent-filter>
       <action android:name="com.whatsapp.otp.OTP_ERROR"/>
   </intent-filter>
</receiver>

In receiver class

<![CDATA[ public class OtpErrorReceiver extends BroadcastReceiver { public static final String OTP_ERROR_KEY = "error"; public static final String OTP_ERROR_MESSAGE_KEY = "error_message"; @Override public void onReceive(Context context, Intent intent) { try { PendingIntent pendingIntent = intent.getParcelableExtra("_ci_"); if (pendingIntent != null) { String packageName = pendingIntent.getCreatorPackage(); if (packageName.equalsIgnoreCase("com.whatsapp") || packageName.equalsIgnoreCase("com.whatsapp.w4b")) { String otpErrorKey = intent.getStringExtra(OTP_ERROR_KEY);String otpErrorMessage = intent.getStringExtra(OTP_ERROR_MESSAGE_KEY); // Handle errors } } } catch (BadParcelableException e) { Log.e("OtpErrorReceiver", e.getLocalizedMessage()); } } } ]]>

Sample app

For more information about the sample app for Android, See WhatsApp One-Time Password (OTP) Sample App on GitHub. The sample app demonstrates how to send and receive OTP passwords and codes by using API operations, how to integrate the one-tap autofill and copy code buttons, how to create a template, and how to start a sample server.