为什么使用 WhatsApp 进行验证？
在 SMS 之外增加另一种发送渠道
WhatsApp 通过互联网连接接收消息。当 Wi-Fi 可用但 SMS 接收不稳定时，它为客户提供了另一种接收验证码的方式。接收者仍需安装 WhatsApp 并保持网络连接正常。减少验证码输入步骤
复制验证码按钮减少了手动输入的繁琐。一键（One-tap）和零点击（Zero-tap）体验可以减少在支持且已集成的 Android 应用之间的切换。对于已经使用 WhatsApp 的客户，这些选项可以让验证更加顺畅。建议在您自己的业务流程中评估对完成率的影响。优化单次完成验证的成本
根据不同市场评估 WhatsApp 作为降低验证成本的可行途径。对比身份验证费率及适用的国际身份验证费率、YCloud 费用、SMS 备用渠道成本以及验证完成率。 建议使用验证渠道总费用除以成功验证次数作为实际衡量指标。Meta 仅针对已送达的消息计费；未送达的消息不会产生相应的 Meta 消息费用。其他费用取决于您的 YCloud 套餐。请参阅 WhatsApp 定价 和 Meta 定价。定位验证流程中的流失点
分别跟踪请求受理、消息送达和成功验证情况。这有助于您区分是发送环节的问题，还是接收或输入验证码时出现的问题。 WhatsApp 仅负责传输验证码。您的验证系统仍需负责判定其是否有效、过期、已被使用，以及是否已针对请求的操作完成授权。开始之前
- 登录 YCloud 并 连接 WABA 与发送号码。
- 准备验证码请求、生成、存储和验证逻辑。本指南使用 WhatsApp Messages API；您的系统拥有验证码的全生命周期管理权限。如需使用 YCloud 的验证服务，请参阅 Verify。
- 准备一个 服务端 API Key 和 Webhook 接收器。
- 使用已主动请求验证码的测试接收者。请求验证码并不代表用户同意后续接收营销消息。
- 如果您需要备用方案，请配置并测试 SMS 渠道。WhatsApp Messages API 不会仅因为您遵循了本指南的建议就自动发送 SMS。
1. 选择验证码体验方式
当不满足设备或应用要求时，一键或零点击体验可以回退到其他方式（例如复制验证码）。请确保支持此回退机制。仅在编辑器中选择该选项并不会自动集成您的客户端应用。
Meta 还记录了在 iOS 26 及更高版本上通过通知提供 OTP 键盘建议的功能。这与 Android 的一键和零点击是分开的；请分别进行测试。请参阅 身份验证模板 和 Meta 身份验证文档。
Meta example: the customer copies the verification code and enters it in your app. The code and expiry shown are demonstration values.
2. 创建身份验证模板
选择 WABA、名称和语言
在 YCloud 中打开目标 WABA 的 模板 ，选择 添加模板，然后选择 身份验证。 使用小写字母、数字和下划线来命名模板，例如login_verification。选择客户的语言，并记录获批的确切名称和语言代码以供发送。请参阅 创建模板。
配置内容和验证码操作
身份验证使用预设的验证码文本，并支持安全和过期提示。请勿在正文中插入常规促销文案、URL、媒体或 Emoji 表情。 选择 Copy code、 Autofill 或 Zero Tap。对于 Autofill 和 Zero Tap，输入实际的 Android 软件包名称和签名哈希，并完成应用集成。Zero Tap 还需要接受适用的条款。 对于 API 配置，请使用当前的supported_apps 规范，而不是较旧的顶级 package_name 和 signature_hash 示例。有关 Android SDK 和握手详情，请参阅 身份验证集成指南。
配置三项独立的过期设置
当前 YCloud 规范支持常规自定义身份验证 TTL 值为 30–900 秒，新消息模板的默认值为 10 分钟 。历史默认值可能会有所不同；请检查保存的
messageSendTtlSeconds。显示的过期通知支持 1–90 分钟 ，但这不会改变后端过期时间，也不会延长常规发送 TTL 范围。
该规范还支持 -1，它会将自定义 TTL 设置为 30 天。不建议将其用于短期有效的验证码，并且这并不意味着立即过期或禁用重试。请参阅 YCloud OpenAPI 规范。
例如，在 10:00 生成并在 10:05 过期的验证码，如果在 10:04 到达，则只剩下一分钟。接收消息不会重置其有效期。TTL 过期会停止尚未完成的发送尝试；它不会撤回已送达客户设备的消息。
提交并检查可用性
提交消息模板并检查其实际审核状态。仅在获得批准且可用后发送。如果被拒绝，请检查原因并遵循消息模板审核与生命周期。不要依赖固定的批准时间。3. 通过 API 发送
客户请求验证码后立即发送。根据您的流程需求选择提交行为：
端点名称
sendDirectly 描述了提交时序。它与处理消息模板生成的 Utility Direct Send 功能是分开的。此流程仍然使用已获批的身份验证模板。
准备请求
- 使用
X-API-Key进行服务端身份验证。 - 对
from和to使用包含国家代码的 E.164 格式号码。 - 将
type设置为template，并使用所选 WABA 的已获批名称和语言。 - 在正文和 OTP 按钮参数中提供相同的验证码。
- 将您的验证请求与 YCloud 消息 ID 关联起来。
externalId有助于对账，但不保证幂等性。
123456 为虚构内容，在生产环境中必须由您的验证系统生成：
sub_type: url；请勿使用普通的营销优惠券代码按钮结构。请参阅复制代码身份验证和发送 WhatsApp 消息。您还可以在已获批的消息模板上选择 更多 → 复制为 cURL ，并对照其配置检查生成的参数。
API 响应成功并不代表已送达。如果请求超时，请在重新发送之前检查可用的消息记录和回调。
4. 接收送达更新
在 开发者 → Webhook 中创建端点，输入您的回调 URL，并订阅whatsapp.message.updated。有关签名验证、确认和重试，请参阅 Webhook 指南。
将每个消息 ID 与其验证请求相关联：
仅在后端验证验证码成功后，才标记验证完成。妥善处理重复和延迟到达的回调，避免较早的状态覆盖较新的状态。可使用 消息日志 进行手动排查。
5. 设计界面和 SMS 降级方案
明确接收渠道
提交前提示验证码将通过 WhatsApp 发送。发送后展示掩码后的接收号码、等待提示、重新发送倒计时及可选的备选方案。允许客户返回并修改号码。
在操作系统允许的情况下，您的应用可以使用 WhatsApp 可用性检测来推荐渠道。但安装并不代表输入的号码已注册或可达。未检测到安装也不能排除在其他设备上接收的可能性。请勿将安装检测用作号码验证。
分别处理失败与延迟
原指南中的 15–60 秒 可以作为试验性的等待区间。请根据实际观察到的延迟和流失率进行调整。这并非 WhatsApp 的硬性要求或送达承诺。
对于同一次验证挑战，您可以通过降级渠道发送仍然有效的相同验证码。如果生成新验证码，请根据策略使前一个验证码失效并向用户说明行为。降级绝不能延长旧验证码的有效期。
使用单个验证请求来控制渠道尝试、冷却时间和完成状态。重复点击或重复、延迟的回调不得触发多条 SMS。如果 WhatsApp 和 SMS 均送达，各渠道均可能产生费用。
6. 上线前测试
上线后，按市场、渠道和设备对比送达率、送达延迟、验证完成率、SMS 降级占比以及单次成功验证的成本。利用这些数据来调整渠道优先级和等待阈值，而不是一味承诺 WhatsApp 总是比 SMS 更快或更便宜。