WhatsApp Business Management API

驗證範本

驗證範本將於 2024 年 7 月 1 日在印度提供使用。

如果您的行動應用程式為用戶提供了經由 WhatsApp 接收一次性密碼或驗證碼的選項，您必須使用驗證範本。

驗證範本包含下列內容：

  • 固定預設文字：<VERIFICATION_CODE> 是您的驗證碼。
  • 安全性免責聲明（選用）：為了您的安全，請勿分享此驗證碼。
  • 失效警告（選用）：此驗證碼將於 <NUM_MINUTES> 分鐘後失效。
  • 可能為一鍵式自動填入按鈕或複製驗證碼按鈕，或者如果使用免點按，則沒有按鈕。

一鍵式自動填入按鈕可提供最佳的使用體驗，為首選的解決方案。但是，一鍵式自動填入按鈕目前僅在 Android 上受支援，且需要額外變更應用程式碼。

請參閱其他守則，瞭解何時適合使用驗證範本。

一鍵式自動填入驗證範本

驗證範本包含一鍵式自動填入按鈕。

當 WhatsApp 用戶點按自動填入按鈕時，WhatsApp 用戶端會觸發一項活動，開啟您的應用程式並傳遞密碼或驗證碼。

請參閱一鍵式自動填入驗證範本，以瞭解其用法。

複製驗證碼驗證範本

複製驗證碼驗證範本可讓您傳送一次性密碼或驗證碼以及複製驗證碼按鈕給用戶。

當 WhatsApp 用戶點擊複製驗證碼按鈕時，WhatsApp 用戶端會將密碼或驗證碼複製到裝置的剪貼簿。接著用戶可切換到應用程式，並將密碼或驗證碼貼到應用程式中。

請參閱複製驗證碼驗證範本，以瞭解其用法。

免點按驗證範本

免點按驗證範本允許您的用戶經由 WhatsApp 接收一次性密碼或驗證碼，且無需離開您的應用程式。

當應用程式中的用戶要求密碼或驗證碼，而您使用免點按驗證範本傳遞時，WhatsApp 用戶端會廣播包含的密碼或驗證碼，然後應用程式便可以使用廣播接收器擷取這些密碼或驗證碼。

請參閱免點按驗證範本，以瞭解其用法。

最佳作法

  • 請先確認用戶的 WhatsApp 電話號碼，再將一次性密碼或驗證碼發送至該號碼。
  • 向用戶明確表示密碼或驗證碼將發送至他們的 WhatsApp 電話號碼，尤其是當您為用戶提供多種接收密碼或驗證碼的方式時。請參閱取得選擇加入，以取得其他秘訣。
  • 當用戶將密碼或驗證碼貼到應用程式中，或應用程式在一鍵式自動填入按鈕流程中接收到密碼或驗證碼時，請向用戶表明應用程式已擷取到。

另請參閱經由 WhatsApp 驗證用戶的最佳作法。

存留時間

如果我們無法向 WhatsApp 用戶傳遞訊息，將繼續嘗試在一段時間內傳遞訊息，稱為存留時間。

預設情況下，訊息的存留時間為 30 天，但新建驗證範本的預設存留時間為 10 分鐘。

如果我們無法在超過驗證範本存留時間的時間內將其傳遞，將停止重試並丟棄訊息。如果驗證範本訊息傳送要求之間的時間超過存留時間，且您沒有收到任何 Webhook，則假設其已遭丟棄。

若要在建立驗證範本時覆寫預設存留時間，請包含 message_send_ttl_seconds 屬性，並將值設定為 60 至 600 秒之間。

此功能提供前所建立之現有範本的存留時間為 30 天。若有需要，您可以編輯現有範本，並設定其 message_send_ttl_seconds 屬性來覆寫存留時間。

您還可以將驗證範本的 message_send_ttl_seconds 屬性設定為 -1。如此可將其存留時間設定為 30 天。

我們鼓勵您為所有驗證範本設定存留時間，最好等於或小於驗證碼過期時間，以確保顧客只在驗證碼仍可用時才收到訊息。

請注意，傳遞失敗的訊息 Webhook 時可能會有輕微的延遲，因此您可能希望在推斷其為丟棄時建置一個小緩衝區。

傳送驗證範本訊息

使用雲端 API 或內部部署 API 在範本訊息中傳送經核准的驗證範本。

範本預覽

您可以使用 WhatsApp Business 帳號 > 訊息範本預覽端點產生各種語言的驗證範本文字預覽，其包含或排除安全建議字串和驗證碼過期字串。

要求語法

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_template_previews
  ?category=AUTHENTICATION,
  &language=<LANGUAGE>, // Optional
  &add_security_recommendation=<ADD_SECURITY_RECOMMENDATION>, // Optional
  &code_expiration_minutes=<CODE_EXPIRATION_MINUTES>, // Optional
  &button_types=<BUTTON_TYPES> // Optional

查詢字串參數

預留位置說明範例值

<LANGUAGE>

逗號分隔的清單

選用項目。


要傳回之語言版本的語言和區域驗證碼的逗號分隔清單。


如果省略，將傳回所有支援語言的版本。

en_US,es_ES

<ADD_SECURITY_RECOMMENDATION>

布林值

選用項目。


若要將安全建議內容字符串包含在回應中，請設定為 true。


如果省略，將不包含安全建議字串。

true

<CODE_EXPIRATION_MINUTES>

Int64

選用項目。


若要在回應中包含驗證碼過期頁尾字串，請設定為整數。


如果省略，將不包含驗證碼過期頁尾字串。


該值指示驗證碼過期前的分鐘數。

最小值為 1，最大值為 90。

10

<BUTTON_TYPES>

逗號分隔的字串清單

必要項目。


指示按鈕類型的逗號分隔字串清單。


如果包含，回應將在回應中包含每個按鈕的按鈕文字。


若是驗證範本，此值必須為 OTP。

OTP

要求範例

curl 'https://graph.facebook.com/v17.0/102290129340398/message_template_previews?category=AUTHENTICATION&languages=en_US,es_ES&add_security_recommendation=true&code_expiration_minutes=10&button_types=OTP' \
-H 'Authorization: Bearer EAAJB...'

回應範例

{
  "data": [
    {
      "body": "*{{1}}* is your verification code. For your security, do not share this code.",
      "buttons": [
        {
          "autofill_text": "Autofill",
          "text": "Copy code"
        }
      ],
      "footer": "This code expires in 10 minutes.",
      "language": "en_US"
    },
    {
      "body": "Tu código de verificación es *{{1}}*. Por tu seguridad, no lo compartas.",
      "buttons": [
        {
          "autofill_text": "Autocompletar",
          "text": "Copiar código"
        }
      ],
      "footer": "Este código caduca en 10 minutos.",
      "language": "es_ES"
    }
  ]
}

批量管理

使用 WhatsApp Business 帳號 > Upsert 訊息範本端點批量更新或建立多種語言的驗證範本，這些範本包含或排除選用的安全和過期警告。

如果具有相符名稱和語言的範本已存在，系統將使用要求的內容更新範本，否則將建立一個新範本。

要求語法

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

張貼內容

{
  "name": "<NAME>",
  "languages": [<LANGUAGES>],
  "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>",
          "package_name": "<PACKAGE_NAME>", // One-tap buttons only
          "signature_hash": "SIGNATURE_HASH>", // One-tap buttons only
        }
      ]
    }
  ]
}

屬性

支援所有範本建立屬性，但以下為例外情況：

  • 不支援 language 屬性。請改用 languages，並將其值設定為語言和區域驗證碼字串的陣列。例如：["en_US","es_ES","fr"]。
  • 不支援 text 屬性。
  • 不支援 autofill_text 屬性。

複製驗證碼要求範例

此範例使用複製驗證碼按鈕建立三個分別為英文、西班牙文和法文的驗證範本。每個範本皆命名為「authentication_code_copy_code_button」，並包含安全建議和過期時間。

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_copy_code_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 10
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE"
        }
      ]
    }
  ]
}'

一鍵式自動填入要求範例

此範例（1）使用名稱「authentication_code_autofill_button」和語言「en_US」更新現有範本，以及（2）使用一鍵式自動填入按鈕建立兩個分別為西班牙文和法文的新驗證範本。兩個新建範本皆命名為「authentication_code_autofill_button」，並包含安全建議和過期時間。

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_autofill_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 15
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "package_name": "com.example.luckyshrub",
          "signature_hash": "K8a%2FAINcGX7"
        }
      ]
    }
  ]
}'

回應範例

{
  "data": [
    {
      "id": "954638012257287",
      "status": "APPROVED",
      "language": "en_US"
    },
    {
      "id": "969725527415202",
      "status": "APPROVED",
      "language": "es_ES"
    },
    {
      "id": "969725530748535",
      "status": "APPROVED",
      "language": "fr"
    }
  ]
}

應用程式範例

請參閱 Github 上適用於 Android 的 WhatsApp 一次性密碼（OTP）應用程式範例。此應用程式範例示範如何透過 API 傳送和接收 OTP 密碼和驗證碼、如何整合一鍵式自動填入和複製驗證碼按鈕、如何建立範本，以及如何建立範例伺服器。

另請參閱