WhatsApp Business 管理 API

身份验证模板

身份验证模板将于 2024 年 7 月 1 日在印度开放。

如果您的移动应用为用户提供了通过 WhatsApp 接收一次性密码或验证码的选项，您就必须使用身份验证模板。

身份验证模板包括以下组件：

  • 固定的预设文本：<VERIFICATION_CODE> 是您的验证码。
  • 安全免责声明（可选）：为安全起见，请勿共享该验证码。
  • 过期警告（可选）：这组验证码将在 <NUM_MINUTES> 分钟后过期。
  • 一键自动填写按钮、复制代码按钮或无任何按钮（如果使用了零轻触）。

一键自动填写按钮可提供最佳用户体验，所以是首选的解决方案。但是，一键自动填写按钮目前仅在 Android 上受支持，而且需要对您应用的代码再作出一些更改。

请查看其他守则，了解身份验证模板的适用场景。

包含一键自动填写功能的身份验证模板

身份验证模板中包含一键自动填写按钮。

当 WhatsApp 用户轻触该自动填写按钮时，WhatsApp 客户端将触发一个活动，这会打开您的应用并向该应用发送密码或验证码。

请参阅包含一键自动填写功能的身份验证模板，了解这类模板的使用方法。

包含复制代码功能的身份验证模板

通过包含复制代码功能的身份验证模板，您可以将一次性密码或验证码连同复制代码按钮一起发送给用户。

当 WhatsApp 用户轻触复制代码按钮时，WhatsApp 客户端就会将密码或验证码复制到设备的剪贴板。然后，用户可以切换到您的应用，将该密码或验证码粘贴到该应用中。

请参阅包含复制代码功能的身份验证模板，了解这类模板的使用方法。

零轻触身份验证模板

通过零轻触身份验证模板，您的用户可以通过 WhatsApp 接收一次性密码或验证码，而无需退出您的应用。

当您应用中的用户请求获取密码或验证码时，如果您使用零轻触身份验证模板发送密码或验证码，WhatsApp 客户端会传播所包含的密码或验证码，然后该应用便可使用广播接收器获取该密码或验证码。

请参阅零轻触身份验证模板，了解这类模板的使用方法。

最佳实践

  • 先确认用户的 WhatsApp 电话号码，再向该号码发送一次性密码或验证码。
  • 明确告知用户，您会将一次性密码或验证码发送至他们的 WhatsApp 电话号码，尤其是当您为用户提供多种方式来接收您发送的一次性密码或验证码时。请参阅获得用户的订阅许可，获取更多建议。
  • 当用户将一次性密码或验证码粘贴到您的应用中时，或应用在一键自动填写按钮流程中收到一次性密码或验证码时，请明确告知用户应用已获取一次性密码或验证码。

另请参阅关于通过 WhatsApp 验证用户身份的最佳实践。

有效期

如果我们无法将消息送达 WhatsApp 用户，我们会在一个称为有效期的时间段内继续尝试将消息送达该用户。

默认情况下，消息有效期为 30 天，但是新建身份验证模板的默认有效期为 10 分钟。

如果我们在超出某个身份验证模板有效期的一段时间内无法将该模板送达，我们将停止重试并弃用该消息。如果从发出身份验证模板消息发送请求的时间到消息送达的时间间隔超出身份验证模板的有效期，且您未收到任何 Webhooks，您即可认为消息已被弃用。

如要在创建身份验证模板时覆盖默认有效期，请在请求中加入 message_send_ttl_seconds 属性，并将其值设在 60 到 600 秒之间。

对于在此功能推出之前创建的现有模板，有效期为 30 天。如有需要，您可以编辑现有模板，并通过设置 message_send_ttl_seconds 属性来覆盖模板的有效期。

您还可以将身份验证模板的 message_send_ttl_seconds 属性设为 -1。这会将此模板的有效期设为 30 天。

鼓励您为所有身份验证模板设置有效期，以不长于验证码到期时间为宜，从而确保您的客户只在验证码仍然可用时收到消息。

请注意，失败消息 Webhooks 的送达可能会略有延迟，因此在推断出消息被弃用时，您可能会需要内置一个小缓冲区。

发送身份验证模板消息

使用云端 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 商业帐号 > 插入/更新消息模板端点批量更新或创建多语言身份验证模板，选择是否在其中加入可选的安全和过期警告。

如果与名称和语言匹配的模板已存在，该模板将使用请求中的内容进行更新，否则系统将创建一个新模板。

请求语法

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

POST 请求正文

{
  "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 发送和接收一次性密码和验证码、如何集成一键自动填写按钮和复制代码按钮、如何创建模板以及如何启动示例服务器。

另请参阅