通过 WhatsApp 发送验证码

使用 WhatsApp 验证码进行注册、登录、账户找回以及敏感操作的二次验证。当客户选择 WhatsApp 后，您的系统会发送一个身份验证模板。客户复制或自动填充验证码，然后由您的后端进行验证。

为什么使用 WhatsApp 进行验证？

在 SMS 之外增加另一个送达渠道

当 SMS 接收不可靠时，WhatsApp 允许客户通过互联网接收验证码。客户只需安装 WhatsApp 并保持有效的网络连接即可。

减少验证码输入步骤

“复制代码”按钮可减少手动输入的繁琐。在受支持且已集成的 Android 应用上，一键点击（One-tap）和免点击（Zero-tap）体验可以减少应用切换。

优化单次完成验证的成本

按市场对比每次成功验证的总渠道成本，包括身份验证费率、适用的跨国身份验证费率、YCloud 费用以及 SMS 回退成本。Meta 仅针对已送达的消息收费；未送达的消息不会产生相应的 Meta 消息费用。其他费用取决于您的 YCloud 套餐。请参阅 WhatsApp 定价和 Meta 定价。

定位验证流程中的流失环节

分别跟踪 API 接收、消息送达和验证成功情况，以准确定位流失节点。您的后端必须拒绝过期、重复使用或无效的验证码。

准备工作

登录 YCloud 并连接 WABA 和发送方。
准备验证码的请求、生成、存储和验证逻辑。本指南使用 WhatsApp Messages API；您的系统拥有验证码的全生命周期控制权。关于 YCloud 的验证服务，请参阅 Verify。
准备好服务端 API 密钥和 Webhook 接收端。
使用主动请求验证码的测试接收者进行测试。验证码请求不代表用户同意后续接收营销消息。
配置 SMS 渠道并在后端实现回退（fallback）规则。

1. 选择验证码体验

体验与集成	示例
复制代码在 WhatsApp 中复制，然后粘贴到您的网站或应用中。跨平台支持。验证码输入与后端验证。
一键点击 / 自动填充点击 Autofill 将验证码传递至您的 Android 应用。集成 Meta 的 OTP Android SDK 并配置您的应用包名以及应用签名密钥哈希。
免点击（Zero-tap）您的 Android 应用无需切换到 WhatsApp 或点击任何按钮即可接收验证码。集成 Meta 的 OTP Android SDK，配置您的应用包名和应用签名密钥哈希，并接受免点击条款。	示意性验证码输入界面。免点击需要 Android 系统支持。

当未满足 Android 一键点击或免点击的前提条件时，支持回退至“复制代码”模式。有关 iOS 键盘建议的信息，请参阅下方的常见问题解答。

2. 创建身份验证模板

选择 WABA、名称和语言

在 YCloud 中打开目标 WABA 的模板页面，选择 添加模板，然后选择 身份验证。名称使用小写字母、数字和下划线，例如 login_verification。选择客户的语言，并记录完全一致的已获批名称和语言代码以供发送使用。请参阅创建模板。

配置内容和验证码操作

身份验证使用预设的验证码文案，并支持安全和过期提示。请勿在正文中插入普通宣传文案、URL、媒体内容或表情符号。选择 复制代码、 自动填充 或 免点击（Zero Tap）。对于自动填充和免点击，请输入真实的 Android 应用包名和签名哈希，并完成应用集成。免点击还要求接受相应的条款。对于 API 配置，请使用当前的 supported_apps 规范，而不是旧版的顶层 package_name 和 signature_hash 示例。有关 Android SDK 和握手细节，请遵循身份验证集成指南。

配置三项独立的过期设置

设置	控制范围	5 分钟示例
后端验证码有效期	服务器在何时拒绝验证码。	生成后 5 分钟。
显示的过期提示	告知客户的信息。	5 分钟，与您的实际策略一致。
投递生存时间 (TTL)	允许尝试投递的时长。	不得超过验证码的剩余有效时长，并考虑到生成与发送之间的时间间隔。

建议在身份验证模板中将 OTP 投递 TTL (messageSendTtlSeconds) 设置为 30–60 秒 。请将其保持在验证码的剩余有效期内。YCloud 支持 30–900 秒，新模板默认值为 10 分钟。显示的过期提示支持 1–90 分钟 ，并且不会在后端强制执行过期。投递 TTL 会终止待处理的投递尝试，但不会撤回已投递的消息。请参阅 YCloud API 规范。

提交并检查可用性

提交模板并查看其实际审核状态。仅在模板通过审核且可用后才发送。如果被拒绝，请查看原因并参考模板审核与生命周期。不要依赖固定的审核时间。

3. 通过 API 发送

在客户请求验证码后立即发送。根据您的业务流程选择提交方式：

端点	行为
`POST /v2/whatsapp/messages/sendDirectly`	同步提交到 WhatsApp Business API；适用于 OTP 流程需要立即获取提交结果的场景。
`POST /v2/whatsapp/messages`	将消息排队以进行异步提交。

两个端点均需使用已批准的身份验证模板。

准备请求

使用 X-API-Key 进行服务端身份验证。
为 from 和 to 使用包含国家/地区代码的 E.164 格式号码。
将 type 设置为 template，并为所选 WABA 使用已批准的名称和语言。
在消息体和 OTP 按钮参数中提供相同的验证码。
将您的验证请求与 YCloud 消息 ID 关联。externalId 有助于对账，但不能保证幂等性。

复制代码请求示例请求体。请替换占位符；123456 为虚构数据，生产环境中必须由您的验证系统生成：

{
  "from": "BUSINESS_PHONE_NUMBER",
  "to": "CUSTOMER_PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "APPROVED_TEMPLATE_NAME",
    "language": { "code": "APPROVED_LANGUAGE_CODE" },
    "components": [
      {
        "type": "body",
        "parameters": [{ "type": "text", "text": "123456" }]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [{ "type": "text", "text": "123456" }]
      }
    ]
  },
  "externalId": "VERIFICATION_REQUEST_REFERENCE"
}

OTP 按钮的发送参数使用 sub_type: url；切勿使用普通的营销优惠券代码按钮结构。请参阅复制代码身份验证和发送 WhatsApp 消息。您还可以在已批准的模板上选择 更多 → 复制为 cURL ，对照其配置检查生成的参数。 API 响应成功并不确认消息已送达。如果请求超时，请在重新发送前检查可用的消息记录和回调。

4. 接收投递更新

在 开发者 → Webhooks中创建一个端点，输入您的回调 URL，并订阅 whatsapp.message.updated。签名验证、确认和重试机制请遵循Webhook 指南。将每个消息 ID 与其验证请求关联：

状态	含义	流程响应
`sent`	已发送，但尚未确认是否到达客户设备。	等待送达或失败更新。
`delivered`	已送达收件人。	等待验证码验证成功。
`read`	已收到已读回执。	请勿标记验证已完成，也不要将缺少已读回执视为失败。
`failed`	发送或投递失败。	在修复配置、重试或切换通道之前检查错误。

仅当您的后端验证通过该验证码后，才标记验证完成。妥善处理重复和延迟的回调，避免较早的状态覆盖较新的状态。使用消息日志进行手动排查。

5. 设计界面和 SMS 回退方案

明确接收通道

在提交前提示验证码将通过 WhatsApp 发送。发送后显示掩码处理的目标号码、等待提示、重发倒计时以及可用的备选方案。允许客户返回修改号码。

策略与体验	前端示例
WhatsApp 优先，SMS 回退首先通过 WhatsApp 发送；如果投递失败或耗时过长，则提供 SMS 选项。
客户自主选择发送前提供 WhatsApp 和 SMS 选项，随后显示重发倒计时和验证码输入界面。

配置 SMS 回退方案

在 WhatsApp 身份验证模板中将 OTP 投递 TTL 设置为 30–60 秒 ，并让 SMS 回退计时器与之保持一致。

触发条件	SMS 回退规则
API 提交明确失败	立即发送 SMS 并排查 API 错误。仅请求超时并不代表被明确拒绝；请检查消息记录和回调。
`whatsapp.message.updated` Webhook 报告 `failed`	立即发送 SMS 并检查错误。常见错误代码为 `131026`（消息无法送达）：该号码可能未在 WhatsApp 注册，但也有可能是其他原因所致。
送达 TTL 已过期，且已收到 `sent` 回执，但未收到 `delivered` 或 `read` 回执	如果验证请求仍然有效，则发送 SMS。在您的后端跟踪送达截止时间；收到延迟到达的 Webhook 时切勿重置 TTL。
WhatsApp 消息已送达、验证已完成或验证码已过期	不要为此请求触发自动 SMS 回退。

Meta 对成功送达的 WhatsApp 消息计费。未送达即过期的消息不会产生 Meta 消息费用；但 SMS 费用仍然适用。仅缺少送达 Webhook 并不等同于未送达，因此如果 WhatsApp 消息在过期前已送达，两个渠道都可能会被计费。请参阅 WhatsApp 定价。即使回调重复或延迟到达，每个验证请求最多发送一次 SMS。复用相同的未过期验证码，或者在发放新验证码时使旧验证码失效。回退不得延长验证码的有效期。

6. 上线前测试

测试项	预期结果
正常验证	正文与按钮中的数值匹配；输入正确的未过期验证码验证成功。
错误、过期或重复使用的验证码	后端根据策略予以拒绝，界面说明相应结果。
请求新验证码	新旧验证码的有效性符合您的既定策略。
接收方离线或延迟	送达 TTL 与验证码有效期相互独立；等待与回退遵循既定配置。
不支持 Android 自动填充的环境	可用的回退机制可让客户继续操作。
iOS 及多设备	在实际客户端上测试通知、复制和填充功能；不要假设各平台行为完全一致。
重复回调、延迟回调、请求超时	不会产生重复结果或不受控的重新发送。
SMS 回退	使用正确的目标号码和有效验证码；验证成功后停止发送。

上线后，按市场、渠道和设备对比送达率、送达延迟、验证完成率、SMS 回退占比以及单次成功验证的成本。利用这些结果来调优渠道优先级和等待阈值。

附加场景：客户发起的验证

在客户发起的验证流程中，客户从应用中打开 WhatsApp，发送一条包含当前验证所需信息的消息，然后返回该应用。这种方式需要一次性质询（challenge）、会话绑定、过期机制、重放保护以及用户确认。

常见问题

如何检查 Android 或 iOS 上是否已安装 WhatsApp？

在 Android 上，请在清单的软件包查询中声明 com.whatsapp 和 com.whatsapp.w4b，然后在 WhatsAppOtpHandler 实例上使用 Meta 的 OTP Android SDK 方法 isWhatsAppInstalled(context)。在 iOS 上，请使用 UIApplication.shared.canOpenURL(URL(string: "whatsapp://otp")!) 并配置应用所需的 URL Scheme 查询权限。安装检查有助于在当前设备上推荐渠道。这并不能确认输入的电话号码是否已在 WhatsApp 注册。请允许客户确认其 WhatsApp 号码并选择其他渠道。请参阅 Meta 的 Android 和 iOS 安装检查说明。

iOS 是否支持一键自动填充或零点击（zero-tap）？

iOS 26 及更高版本 默认对所有身份验证模板启用键盘建议功能。iOS 会检测 WhatsApp 推送通知中的验证码，并在键盘中提供一键自动填充建议。无需对集成进行任何更改。较早的 iOS 版本不支持此自动填充体验；请使用复制代码模板。Android 的一键按钮集成与零点击是相互独立的体验； 零点击仅适用于 Android。请参阅 Meta 的键盘建议说明。

客户可以在关联设备上查看验证码吗？

身份验证码仅可在客户的 WhatsApp 主设备 上查看。关联设备会显示一条掩码处理后的消息，提示客户查看其主设备。此 Cloud API 安全功能默认处于启用状态，无需更改代码，且无法进行配置或自定义。请参阅 Meta 的已关联设备安全说明。

​为什么使用 WhatsApp 进行验证？

​在 SMS 之外增加另一个送达渠道

​减少验证码输入步骤

​优化单次完成验证的成本

​定位验证流程中的流失环节

​准备工作

​1. 选择验证码体验

​2. 创建身份验证模板

​选择 WABA、名称和语言

​配置内容和验证码操作

​配置三项独立的过期设置

​提交并检查可用性

​3. 通过 API 发送

​准备请求

​4. 接收投递更新

​5. 设计界面和 SMS 回退方案

​明确接收通道

​配置 SMS 回退方案

​6. 上线前测试

​附加场景：客户发起的验证

​常见问题

​如何检查 Android 或 iOS 上是否已安装 WhatsApp？

​iOS 是否支持一键自动填充或零点击（zero-tap）？

​客户可以在关联设备上查看验证码吗？