背景信息

自2023年5月1日起，WhatsApp推出了包含一次性密碼按鈕的身份驗證模板（Authentication），自2023年5月29日起，所有新建的身份驗證模板都必須包含一次性密碼按鈕。更多關于身份驗證模板的信息請參見WhatsApp模板類型說明。

身份驗證模板

模板組成

包含一次性密碼按鈕的身份驗證模板由以下部分組成：

• 身份驗證模板的預設固定文本：

  • <VERIFICATION_CODE> 是您的驗證碼。

  • 安全免責聲明（可選）：為安全起見，請勿共享該驗證碼。

  • 過期警告（可選）：這組驗證碼將在<NUM_MINUTES>分鐘后過期。

• 按鈕：復制驗證碼按鈕（Copy code）或一鍵自動填寫按鈕（Autofill）。

示例圖：

模板規則限制

• 包含一次性密碼按鈕的身份驗證模板僅由預設文本和按鈕組成。

• 身份驗證模板的內容或參數不允許使用網址、媒體（圖片、音頻、視頻、文件等）和表情符號。

• 身份驗證模板使用參數最多支持15 個字符，即驗證碼最大長度為15位。

按鈕

身份驗證模板必須包含復制驗證碼按鈕（Copy code）或一鍵自動填寫按鈕（Autofill）。當用戶點擊按鈕時，不同按鈕的工作方式不同：

• 復制驗證碼按鈕：會將一次性密碼或驗證碼復制到用戶的剪貼板。然后，用戶可以手動切換到您的應用，將一次性密碼或驗證碼粘貼到應用界面。

• 一鍵自動填寫按鈕：會自動加載您的應用，并向該應用傳遞一次性密碼或驗證碼。

一鍵自動填寫按鈕可提供最佳用戶體驗，所以是首選的解決方案。但是，目前僅安卓系統手機（Android）支持一鍵自動填寫按鈕，并且此類按鈕需要更改您應用的代碼，才能執行“握手”，另外還需要更改應用的簽名密鑰哈希值。請參閱下方握手和 應用簽名密鑰哈希值部分。

最佳實踐

• 在發送一次性密碼或驗證碼前，先確認用戶的WhatsApp電話號碼，再向該號碼發送一次性密碼或驗證碼。

• 明確告知用戶，一次性密碼或驗證碼將發送至他們的WhatsApp電話號碼，尤其是當您為用戶提供多種方式來接收一次性密碼或驗證碼時。

• 當用戶將一次性密碼或驗證碼粘貼到您的應用中時，或應用在一鍵自動填寫按鈕流程中收到一次性密碼或驗證碼時，請明確告知用戶應用已獲取一次性密碼或驗證碼。

參數說明

應用簽名密鑰哈希值

如要創建使用一鍵自動填寫按鈕的身份驗證模板，您必須在components數組中加入應用簽名密鑰哈希值。

如要計算您的哈希值，請遵循Google有關計算應用的哈希字符串的說明。

或者，如果您按照Google說明下載了應用簽名密鑰證書，您可以結合使用該證書和sms_retriever_hash_v9.sh shell腳本來計算哈希值。

握手

如果您應用中的用戶請求獲取一次性密碼或驗證碼，并選擇將其發送到他們的WhatsApp電話號碼，您首先應執行“握手”，然后調用我們的API來發送身份驗證模板消息。在收到該消息后，WhatsApp應用將執行資格檢查。如果沒有錯誤，WhatsApp將啟動意圖并向用戶顯示該消息。最后，當用戶點擊該消息的一鍵自動填寫按鈕時，WhatsApp應用會自動加載您的應用并向傳遞一次性密碼或驗證碼。

資格檢查

在收到身份驗證模板消息之后，WhatsApp應用會執行以下檢查。如果任意檢查失敗，一鍵自動填寫按鈕將被替換為復制驗證碼按鈕。

• “握手”是在發送消息前的10分鐘內發起。

• 消息中的應用包名（創建模板時在components數組的package_name屬性中定義）與意圖上設置的應用包名匹配。WhatsApp應用將使用您的應用程序提供的PendingIntent對象中調用的getCreatorPackage方法判斷項目包名稱是否匹配。

• 消息中的應用簽名密鑰哈希值（創建模板時在components數組的signature_hash屬性中定義）與您所安裝應用的簽名密鑰哈希值匹配。

• 消息包含一鍵自動填寫按鈕的文本。

• 您的應用已定義用于接收一次性密碼或驗證碼的活動。請參閱下方活動（Activity）部分。

Android通知

僅在以下情況下，表示已收到WhatsApp身份驗證模板消息的Android通知才會顯示在用戶的Android設備上：

• 用戶使用所發送消息的接收電話號碼（賬戶）登錄WhatsApp應用。

• 用戶登錄您的應用。

• Android操作系統是 KitKat（Android 4.4，API 19）或更高版本。

• WhatsApp應用已啟用顯示通知（設置>通知）。

• 已為WhatsApp應用啟用設備層級通知。

• 在WhatsApp應用中，用戶與您的企業之間過去的消息對話未設為靜音。

客戶端實現

在您的應用中實現以下活動（activity）和類（class）。

活動（Activity）

聲明可接收一次性密碼或驗證碼的活動和意圖篩選條件。意圖篩選條件必須具有操作名稱 com.whatsapp.otp.OTP_RETRIEVED。

在收到身份驗證模板消息（且該消息已通過所有資格檢查）后，WhatsApp應用將立即開始執行此活動。

公共類（Public Class）

定義在一次性密碼或驗證碼傳遞到您的應用后，可接受該一次性密碼或驗證碼的活動公共類。

發起“握手”

以下示例展示了使用WhatsApp應用發起“握手”的一種方法。

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);
}

錯誤信號

如果您的消息未通過WhatsApp的任意一項資格檢查，一鍵自動填寫按鈕將被替換為復制驗證碼按鈕。此外，還可能有設備、WhatsApp應用設置阻止消息通知。為幫助調試，WhatsApp應用會通過傳遞com.whatsapp.OTP_ERROR意圖來顯示一些錯誤信息。在這種情況下，您將收到錯誤密鑰和消息，而不是用戶的一次性密碼或驗證碼。

請注意，其中某些錯誤信號只有在Android模擬器中運行WhatsApp應用時才會出現。

集成

錯誤信號通過廣播意圖送達，因此必須運行BroadcastReceiver才能收到錯誤信號。

使用 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>

使用接收器類

<![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()); } } } ]]>

應用示例

請訪問Github網站，參閱適用于Android平臺的WhatsApp一次性密碼 (OTP) 應用示例。該應用示例展示了如何通過 API 發送和接收一次性密碼和驗證碼、如何集成一鍵自動填寫按鈕和復制驗證碼按鈕、如何創建模板以及如何啟動示例服務器。?