登录开始免费试用
Meta Tech Provider

在 WhatsApp 上发送验证码(OTP)

要在 WhatsApp 上发送验证码(OTP),企业需创建一个身份验证消息模板。该模板采用 Meta 规定的固定格式“<代码> 为您的验证码。”,并带有复制代码或一键按钮。企业的后端通过 Cloud API 发送,并将验证码同时填入正文和按钮。验证码最多 15 个字符,可选的有效期提示为 1 至 90 分钟。

easyCoexistence 通过 Coexistence 将您的 WhatsApp Business 号码连接到 Meta 的 Cloud API,并为您的后端提供发送身份验证模板所需的一切:Send 端点、访问令牌,以及通过您的 AI 使用的 create_template 和 get_template_status。

15 characters

身份验证模板可接受的最长参数;其内容和参数中不允许 URL、媒体和表情符号。

1 to 90 minutes

code_expiration_minutes 的取值范围,它会在消息中添加一行“此代码将在 N 分钟后过期。”

10 minutes

身份验证模板的默认存活时间(TTL);可在 30 秒至 15 分钟之间设置。

131062

当身份验证模板被发送到企业范围用户 ID 而非电话号码时返回的错误。

Primary device

身份验证消息只会送达用户的主要 WhatsApp 设备;已关联的设备只会看到一条提示。

20 msg/s

Coexistence 号码的固定吞吐量,也是突发登录验证码时的上限。

什么是 WhatsApp 身份验证模板?

这是 Meta 唯一允许用于一次性密码和验证码的格式:如果应用通过 WhatsApp 提供验证码,就必须使用它,实用类或营销类模板不得包含密码。正文固定为“<代码> 为您的验证码。”,另有两行可选内容:“为了您的安全,请勿分享此代码。”和“此代码将在 <N> 分钟后过期。”您可以选择的是按钮。WhatsApp 会禁止转发这类消息;在 iOS 26 及更高版本上,验证码还会作为键盘建议出现,无需您做任何设置。

Copy codeTapping copies the code to the clipboard; the user pastes it in your app or site
One-tap autofillAndroid: the button opens your app and hands it the code; needs app changes and a handshake
Zero-tapAndroid only, no button: your app receives the code through a broadcast receiver

如何创建身份验证模板?

可以从 WhatsApp Manager 中的模板库选择,也可以通过 API 提交,您的 AI 可以使用 create_template 并将类别设为 AUTHENTICATION 完成此操作。您无需提供正文:Meta 会根据您的设置,以您选择的语言生成正文,并在创建时把 OTP 按钮转换为 URL 按钮。每种语言一个模板。连接器的 create_template 不会传递 message_send_ttl_seconds,因此除非您通过 Meta 的 API 修改,否则将使用 10 分钟的默认存活时间。

create_template arguments for a copy-code template
{
  "connection_id": "<from list_numbers>",
  "name": "login_code",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "components": [
    { "type": "BODY", "add_security_recommendation": true },
    { "type": "FOOTER", "code_expiration_minutes": 5 },
    { "type": "BUTTONS", "buttons": [
      { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy code" }
    ]}
  ]
}

您的后端如何发送验证码?

每个验证码向号码的 /messages 端点发送一次请求,访问令牌可从 get_api_credentials 获取,或从控制台的“接入您自己的系统”卡片获取。同一个验证码要填两次:一次在正文参数中,一次在索引为 0 的 URL 按钮参数中,且收件人必须是电话号码。发送前,后端会生成验证码,保存其哈希值、过期时间和尝试次数计数器,之后再将用户输入的内容与该哈希值进行比对。

Sending a login code from your backend
POST https://graph.facebook.com/<VERSION>/<PHONE_NUMBER_ID>/messages
Authorization: Bearer <ACCESS_TOKEN>

{
  "messaging_product": "whatsapp",
  "to": "5511987654321",
  "type": "template",
  "template": {
    "name": "login_code",
    "language": { "code": "en_US" },
    "components": [
      { "type": "body",
        "parameters": [{ "type": "text", "text": "482913" }] },
      { "type": "button", "sub_type": "url", "index": "0",
        "parameters": [{ "type": "text", "text": "482913" }] }
    ]
  }
}

为什么验证码由您的后端生成,而不是由自动化流程生成?

因为登录系统必须生成、记住并校验验证码,只有该系统知道何时需要验证码。自动化流程用于回复客户发来的消息,而登录页面从不会通过您的号码发送消息。模板本身也排除了自动化:OTP 按钮把验证码作为按钮变量携带,而“发送模板”步骤只填充正文变量,因此无法发送身份验证模板。您的 AI 可以通过 send_template 发送一条,该方法会把按钮组件传给 Meta,但那只适用于测试,而不适用于登录流程。

什么让 WhatsApp OTP 流程更安全?

Meta 的最佳实践与该格式的限制指向同一份清单。以下各项只需您的后端和 Cloud API 即可完成:

  • 在发送第一个验证码之前,请与用户确认 WhatsApp 号码,并说明验证码将通过 WhatsApp 送达。
  • 将存活时间设为不超过验证码的有效期,避免延迟送达时出现已失效的验证码。
  • 限制每个号码的尝试次数和重发次数,并在首次使用后让验证码失效。
  • 不要把 WhatsApp 验证码作为账户恢复的唯一验证因素:被回收的电话号码仍可能关联到旧的 WhatsApp 账户。
  • 监控状态 Webhook,验证码送达失败时提供短信或电子邮件作为替代。

如果号码同时在 WhatsApp Business 应用中使用,会有什么变化?

发送方式与任何 Cloud API 号码相同,最高可达每秒 20 条消息。Meta 会把通过 API 发送的消息同步到应用的聊天中,因此在 Coexistence 号码上,您发送的验证码也会出现在商务手机的这些聊天中;请只让您信任的人接触该手机,或使用单独的号码发送验证码。Meta 的最佳实践还要求每个企业使用自己的号码发送身份验证模板,不得在企业之间共用同一号码。身份验证是付费模板类别,按收件人所在国家/地区对每条已送达的消息计费,部分市场设有单独的国际身份验证费率;easyCoexistence 不加收任何费用。

设置方法

  1. Connect the numberConnect your WhatsApp Business number to easyCoexistence through Meta's Coexistence flow, or use a separate number reserved for codes.
  2. Create the authentication templateAsk your AI to submit login_code with create_template, category AUTHENTICATION, a copy-code button and an expiry, then check get_template_status for APPROVED.
  3. Store the credentials on your serverCall get_api_credentials or open "Plug in your own system" in the dashboard, and put the Send endpoint and access token in your backend's secrets.
  4. Build generate, send and verifyGenerate the code, store its hash with an expiry, send the template with the code in the body and button, then check the user's entry against the hash.
  5. Handle failuresRead failed statuses from the number's webhook, then offer SMS or email and show the user which number the code went to.

常见错误

  • 把验证码写入实用类模板,例如“您的代码为 {{1}}”。Meta 只允许在身份验证模板中使用密码,发现实用类或营销类模板包含密码时会予以拒绝。
  • 只在正文中发送验证码。复制代码按钮需要与其参数相同的值,Meta 要求请求中同时包含两次验证码。
  • 对旧的身份验证模板保留 30 天的 TTL。手机离线一小时后会收到已过期的验证码;请将其设为不超过验证码的有效期。
  • 将验证码发送到企业范围用户 ID。身份验证模板只发送到电话号码,Meta 会返回错误 131062。
使用 EasyCoexistence 完成这些操作

号码 24/7 全天候受到监控,如果断开连接会导致登录验证码无法发送,我们会通过电子邮件通知您。每个号码每月 US$ 9 起,号码越多越便宜,最低降至 US$ 0.75,并提供前 3 天免费试用。

常见问题

WhatsApp OTP 比短信验证码便宜吗?

Meta 按收件人所在国家/地区的费率对每条已送达的身份验证消息收费,部分市场设有特殊费率。短信价格因运营商和线路而异。切换之前,请将 Meta 的费率表与您的短信服务商在主要国家的费率进行比较。

这与 WhatsApp 的两步验证 PIN 相同吗?

不同。两步验证是保护企业自己 WhatsApp 号码的六位数 PIN。身份验证模板则向您的客户发送验证码,以便您的应用或网站确认他们的身份。

用户需要选择加入才能接收验证码吗?

需要。Meta 的政策规定,企业在向他人发送消息之前必须获得许可,其 OTP 指南建议提供多种渠道选择,例如 WhatsApp、短信或电子邮件。在登录页面上,于号码旁选择 WhatsApp,即构成该许可。

代理机构能否用一个号码为多个客户发送验证码?

不能。Meta 的最佳实践要求每个企业为身份验证模板拥有自己的 WhatsApp Business 账户和电话号码;在企业之间共用一个号码违反 Meta 的条款和政策。请改为为每个客户连接一个号码。

继续阅读

准备开始了吗?

几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间