> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # 通过 WhatsApp 发送验证码 使用 WhatsApp 验证码进行注册、登录、账户找回以及敏感操作的额外验证。当客户选择 WhatsApp 后，您的系统将发送一个身份验证模板。客户复制或自动填充验证码，然后由您的后端进行验证。 ## 为什么使用 WhatsApp 进行验证？ ### 在 SMS 之外增加另一种发送渠道 WhatsApp 通过互联网连接接收消息。当 Wi-Fi 可用但 SMS 接收不稳定时，它为客户提供了另一种接收验证码的方式。接收者仍需安装 WhatsApp 并保持网络连接正常。 ### 减少验证码输入步骤 复制验证码按钮减少了手动输入的繁琐。一键（One-tap）和零点击（Zero-tap）体验可以减少在支持且已集成的 Android 应用之间的切换。对于已经使用 WhatsApp 的客户，这些选项可以让验证更加顺畅。建议在您自己的业务流程中评估对完成率的影响。 ### 优化单次完成验证的成本 根据不同市场评估 WhatsApp 作为降低验证成本的可行途径。对比身份验证费率及适用的国际身份验证费率、YCloud 费用、SMS 备用渠道成本以及验证完成率。 建议使用验证渠道总费用除以成功验证次数作为实际衡量指标。Meta 仅针对已送达的消息计费；未送达的消息不会产生相应的 Meta 消息费用。其他费用取决于您的 YCloud 套餐。请参阅 [WhatsApp 定价](/zh/documentation/whatsapp-business-platform/pricing-limits-and-quality/whatsapp-pricing) 和 [Meta 定价](https://business.whatsapp.com/products/platform-pricing)。 ### 定位验证流程中的流失点 分别跟踪请求受理、消息送达和成功验证情况。这有助于您区分是发送环节的问题，还是接收或输入验证码时出现的问题。 WhatsApp 仅负责传输验证码。您的验证系统仍需负责判定其是否有效、过期、已被使用，以及是否已针对请求的操作完成授权。 ## 开始之前 1. 登录 [YCloud](https://www.ycloud.com/console/#/entry/login) 并 [连接 WABA 与发送号码](/zh/documentation/quick-start/connect-whatsapp-to-ycloud)。 2. 准备验证码请求、生成、存储和验证逻辑。本指南使用 WhatsApp Messages API；您的系统拥有验证码的全生命周期管理权限。如需使用 YCloud 的验证服务，请参阅 [Verify](/zh/documentation/integrations/channels/verify/index)。 3. 准备一个 [服务端 API Key](/zh/documentation/developer/manage-api-keys) 和 [Webhook 接收器](/zh/documentation/developer/webhooks)。 4. 使用已主动请求验证码的测试接收者。请求验证码并不代表用户同意后续接收营销消息。 5. 如果您需要备用方案，请配置并测试 SMS 渠道。WhatsApp Messages API 不会仅因为您遵循了本指南的建议就自动发送 SMS。 ## 1. 选择验证码体验方式 | 体验方式 | 客户操作 | 您需要准备的内容 | 适用场景 | | - | - | - | - | | **复制验证码** | 在 WhatsApp 中复制，然后在您的网站或应用中输入验证码。 | 输入界面和后端验证逻辑。 | 网站、多平台以及初期集成。 | | **一键 / 自动填充** | 点击按钮将验证码直接传递给受支持的 Android 应用。 | 应用包名、签名哈希和握手集成。 | 减少在 Android 上的应用切换和粘贴操作。 | | **零点击** | 受支持的 Android 应用无需切换到 WhatsApp 即可接收验证码。 | Android 集成、资格检查以及接受适用条款。 | 在能够测试支持条件的情况下进一步减少交互。 | 当不满足设备或应用要求时，一键或零点击体验可以回退到其他方式（例如复制验证码）。请确保支持此回退机制。仅在编辑器中选择该选项并不会自动集成您的客户端应用。 Meta 还记录了在 iOS 26 及更高版本上通过通知提供 OTP 键盘建议的功能。这与 Android 的一键和零点击是分开的；请分别进行测试。请参阅 [身份验证模板](/zh/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/index) 和 [Meta 身份验证文档](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/)。 Meta 身份验证示例，带有指向“复制验证码”的短箭头。 来源：[Meta 身份验证模板](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates/)。 ## 2. 创建身份验证模板 ### 选择 WABA、名称和语言 在 YCloud 中打开目标 WABA 的 **模板** ，选择 **添加模板**，然后选择 **身份验证**。 使用小写字母、数字和下划线来命名模板，例如 `login_verification`。选择客户的语言，并记录获批的确切名称和语言代码以供发送。请参阅 [创建模板](/zh/documentation/channels/whatsapp-accounts-management/template-management/create-template/index)。 ### 配置内容和验证码操作 身份验证使用预设的验证码文本，并支持安全和过期提示。请勿在正文中插入常规促销文案、URL、媒体或 Emoji 表情。 选择 **Copy code**、 **Autofill** 或 **Zero Tap**。对于 Autofill 和 Zero Tap，输入实际的 Android 软件包名称和签名哈希，并完成应用集成。Zero Tap 还需要接受适用的条款。 对于 API 配置，请使用当前的 `supported_apps` 规范，而不是较旧的顶级 `package_name` 和 `signature_hash` 示例。有关 Android SDK 和握手详情，请参阅 [身份验证集成指南](/zh/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/index)。 ### 配置三项独立的过期设置 | 设置 | 控制的内容 | 5 分钟示例 | | - | - | - | | 后端验证码过期时间 | 您的服务器何时拒绝该验证码。 | 生成后 5 分钟。 | | 显示的过期通知 | 告知客户的信息。 | 5 分钟，与您的实际策略一致。 | | 发送生存时间（TTL） | 允许尝试发送的时长。 | 不超过验证码的剩余有效时长，并计入生成到发送之间的时间。 | 当前 YCloud 规范支持常规自定义身份验证 TTL 值为 **30–900 秒**，新消息模板的默认值为 **10 分钟** 。历史默认值可能会有所不同；请检查保存的 `messageSendTtlSeconds`。显示的过期通知支持 **1–90 分钟** ，但这不会改变后端过期时间，也不会延长常规发送 TTL 范围。 该规范还支持 `-1`，它会将自定义 TTL 设置为 30 天。不建议将其用于短期有效的验证码，并且这并不意味着立即过期或禁用重试。请参阅 [YCloud OpenAPI 规范](https://newdocs.ycloud.com/openapi/endpoints/ycloud-api-v2.yaml)。 例如，在 10:00 生成并在 10:05 过期的验证码，如果在 10:04 到达，则只剩下一分钟。接收消息不会重置其有效期。TTL 过期会停止尚未完成的发送尝试；它不会撤回已送达客户设备的消息。 ### 提交并检查可用性 提交消息模板并检查其实际审核状态。仅在获得批准且可用后发送。如果被拒绝，请检查原因并遵循[消息模板审核与生命周期](/zh/documentation/whatsapp-business-platform/messaging/message-templates/template-review-and-lifecycle)。不要依赖固定的批准时间。 ## 3. 通过 API 发送 客户请求验证码后立即发送。根据您的流程需求选择提交行为： | 端点 | 行为 | | - | - | | `POST /v2/whatsapp/messages/sendDirectly` | 同步提交到 WhatsApp Business API；当 OTP 流程需要立即获取提交结果时非常有用。 | | `POST /v2/whatsapp/messages` | 将消息加入队列以进行异步提交。 | 端点名称 `sendDirectly` 描述了提交时序。它与处理消息模板生成的 Utility Direct Send 功能是分开的。此流程仍然使用已获批的身份验证模板。 ### 准备请求 * 使用 `X-API-Key` 进行服务端身份验证。 * 对 `from` 和 `to` 使用包含国家代码的 E.164 格式号码。 * 将 `type` 设置为 `template`，并使用所选 WABA 的已获批名称和语言。 * 在正文和 OTP 按钮参数中提供相同的验证码。 * 将您的验证请求与 YCloud 消息 ID 关联起来。`externalId` 有助于对账，但不保证幂等性。 Copy code 请求体示例。请替换占位符；`123456` 为虚构内容，在生产环境中必须由您的验证系统生成： ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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`；请勿使用普通的营销优惠券代码按钮结构。请参阅[复制代码身份验证](/zh/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/copy-code-authentication)和[发送 WhatsApp 消息](/zh/api-reference/guides/whatsapp-platform/send-whatsapp-message)。您还可以在已获批的消息模板上选择 **更多 → 复制为 cURL** ，并对照其配置检查生成的参数。 API 响应成功并不代表已送达。如果请求超时，请在重新发送之前检查可用的消息记录和回调。 ## 4. 接收送达更新 在 **开发者 → Webhook** 中创建端点，输入您的回调 URL，并订阅 `whatsapp.message.updated`。有关签名验证、确认和重试，请参阅 [Webhook 指南](/zh/documentation/developer/webhooks)。 将每个消息 ID 与其验证请求相关联： | 状态 | 含义 | 流程响应 | | - | - | - | | `sent` | 已发送，但未确认是否到达客户设备。 | 等待送达或失败更新。 | | `delivered` | 已送达收件人。 | 等待验证码验证成功。 | | `read` | 已收到已读回执。 | 请勿直接标记验证完成，也不要将缺少已读回执视为失败。 | | `failed` | 发送或送达失败。 | 在修改配置、重试或切换渠道之前，请先检查错误原因。 | 仅在后端验证验证码成功后，才标记验证完成。妥善处理重复和延迟到达的回调，避免较早的状态覆盖较新的状态。可使用 [消息日志](/zh/documentation/channels/whatsapp-accounts-management/data-analysis/message-logs) 进行手动排查。 ## 5. 设计界面和 SMS 降级方案 ### 明确接收渠道 提交前提示验证码将通过 WhatsApp 发送。发送后展示掩码后的接收号码、等待提示、重新发送倒计时及可选的备选方案。允许客户返回并修改号码。 | 策略 | 适用场景 | 体验 | | - | - | - | | WhatsApp 优先，SMS 降级 | 数据表明客户主要使用 WhatsApp。 | 明确首选渠道；在失败或延迟时提供 SMS 选项，或根据公布的降级策略自动发送。 | | 客户自主选择 | 针对不同市场、设备或用户偏好。 | 同时提供 WhatsApp 和 SMS 选项，并记住相应的偏好设置。 | 在操作系统允许的情况下，您的应用可以使用 WhatsApp 可用性检测来推荐渠道。但安装并不代表输入的号码已注册或可达。未检测到安装也不能排除在其他设备上接收的可能性。请勿将安装检测用作号码验证。 ### 分别处理失败与延迟 | 场景 | 建议操作 | | - | - | | 明确失败 | 对错误进行分类。在降级策略允许且号码与验证码仍有效时使用 SMS。修复 API-key、模板或账户错误，而不是仅用降级来掩盖问题。 | | 提交后未及时收到送达确认 | 在提供其他渠道或应用降级前设置可配置的等待时间。缺少确认并不代表未送达。 | | 已送达但未完成验证 | 保持输入和重试选项可用；不要仅因为验证未完成就不断重新发送。 | | 验证已完成或验证码已过期 | 停止针对此请求的后续发送。 | 原指南中的 **15–60 秒** 可以作为试验性的等待区间。请根据实际观察到的延迟和流失率进行调整。这并非 WhatsApp 的硬性要求或送达承诺。 对于同一次验证挑战，您可以通过降级渠道发送仍然有效的相同验证码。如果生成新验证码，请根据策略使前一个验证码失效并向用户说明行为。降级绝不能延长旧验证码的有效期。 使用单个验证请求来控制渠道尝试、冷却时间和完成状态。重复点击或重复、延迟的回调不得触发多条 SMS。如果 WhatsApp 和 SMS 均送达，各渠道均可能产生费用。 ## 6. 上线前测试 | 测试项 | 预期结果 | | - | - | | 正常验证 | 正文和按钮中的值匹配；正确且未过期的验证码验证成功。 | | 错误、过期或已使用的验证码 | 后端根据策略拒绝，界面清晰展示结果。 | | 请求新验证码 | 新旧验证码的有效性符合您的策略。 | | 接收者离线或延迟 | 消息送达 TTL 与验证码有效期相互独立；等待和降级遵循配置。 | | 不支持 Android 自动填充的条件 | 提供可用的备选方案以便客户继续操作。 | | iOS 及多设备 | 在实际客户端上测试通知、复制和填充行为；不要假定表现完全一致。 | | 重复回调、延迟回调、请求超时 | 不会产生重复的处理结果或无节制的重发。 | | SMS 降级 | 使用正确的目的地和有效验证码；验证成功后停止发送。 | 上线后，按市场、渠道和设备对比送达率、送达延迟、验证完成率、SMS 降级占比以及单次成功验证的成本。利用这些数据来调整渠道优先级和等待阈值，而不是一味承诺 WhatsApp 总是比 SMS 更快或更便宜。 ## 补充场景：客户发起的验证 在客户发起的验证流程中，客户从应用中打开 WhatsApp，发送一条包含当前验证所需信息的消息，然后返回应用。对此方案应单独进行评估。单凭一条普通的 WhatsApp 入站消息，不足以直接让用户登录网站或应用。 这种方案需要使用一次性质询（one-time challenge）、会话绑定、过期机制、重放保护以及用户确认。引用的 YCloud 资料并未提供现成的登录功能，因此本指南未将其作为默认的集成步骤进行介绍。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.