WhatsApp Business 管理 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>

Boolean

此為選用項目。


如果您希望回覆中包含安全建議正文字串，請將此值設定為 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 屬性。

複製代碼要求範例

此範例建立了 3 個分別以英文、西班牙文和法文顯示的驗證類別範本，當中均有複製代碼按鈕。每個範本均以「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）建立了 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 密碼和代碼、如何整合一鍵自動填入和複製代碼按鈕、如何建立範本，以及如何創立伺服器範例。

另請參閱