> ## 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.

# 身份验证模板

> 选择复制验证码、一键或零点击发送方式，并区分 OTP 过期时间与消息发送有效期。

使用身份验证模板发送用于身份验证的一次性密码 (OTP)，例如登录、账户找回或交易确认验证。

Meta 要求此类用途必须使用身份验证模板。请勿通过营销或效用模板发送身份验证码。身份验证内容采用受限格式，而非通用的推广消息。

## 选择验证码发送体验

| 体验 | 客户操作 | 您需要准备的内容 |
| - | - | - |
| 复制代码 | 从 WhatsApp 复制验证码并输入到您的应用中。 | 您应用中的验证码输入流程。 |
| 一键自动填充 | 点击按钮将验证码传递给支持的 Android 应用。 | 应用集成、软件包名称、签名信息以及所需的握手流程。 |
| 零点击 | 支持的 Android 应用无需客户切换到 WhatsApp 即可接收验证码。 | 所需的应用集成和零点击资格检查。 |

请选择您的应用程序能够稳定支持的最简单体验。不要仅仅因为模板编辑器提供了该选项就选择一键或零点击。

不支持的设备或未通过资格检查的情况可以使用“复制代码”作为后备方案。Meta 还说明了自 2026 年 6 月 15 日起，在 iOS 26 及更高版本上支持原生 OTP 键盘建议；该客户端行为与 Android 一键和零点击集成不同。发布前请测试实际的客户设备和应用组合。

<a id="copy-code-authentication-templates" />

<a id="one-tap-autofill-authentication-templates" />

<a id="zero-tap-authentication-templates" />

## 了解模板内容

身份验证格式包括验证码、验证码发送操作以及支持的安全或过期提示文案。它不能用于多媒体、营销文案或常规账户通知。

<Frame caption="Authentication content uses preset text and a code-delivery action. Meta labels each part in this example.">
  <div style={{ position: "relative", width: "100%", maxWidth: "680px", margin: "0 auto" }}>
    <img src="https://mintcdn.com/lchnan/Q9LYCM-XEE-Z8muf/product-assets/whatsapp-platform-2026-09-22/meta-authentication-components.png?fit=max&auto=format&n=Q9LYCM-XEE-Z8muf&q=85&s=d91f4d4ad03a1f5d54dded42d229a00c" alt="标注了验证码、安全免责声明、过期警告和自动填充按钮的 Meta 身份验证消息。" style={{ width: "100%", height: "auto", margin: 0 }} width="2224" height="2211" data-path="product-assets/whatsapp-platform-2026-09-22/meta-authentication-components.png" />
  </div>
</Frame>

来源：[Meta 官方示例](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates/)。

优惠券的 **复制代码** 按钮属于营销格式；它不是身份验证模板。

有关支持的字段，请参阅 YCloud 的 [身份验证模板设置](/zh/documentation/channels/whatsapp-accounts-management/template-management/create-template/index) 和 [模板 API 指南](/zh/api-reference/guides/whatsapp-platform/manage-whatsapp-templates)。

## 区分三种不同的过期时间

| 设置 | 控制内容 |
| - | - |
| 应用程序中的 OTP 过期时间 | 后端停止接受验证码的时间。 |
| 向客户展示的过期文案 | 消息中关于验证码有效期的描述。 |
| 消息发送有效期 | 平台尝试发送该消息的最长时间。 |

显示过期警告并不会让您的后端自动拒绝过期的验证码。请在验证系统本身进行配置。

请选择符合验证码实际有效期的发送有效期。包含已过期验证码的延迟消息即使发送成功，也会造成不良的登录体验。

## 配置送达时仍然有效的验证码

在 YCloud 中，选择 **身份验证**，选择验证码发送体验，并配置支持的安全与过期选项。消息文本受到严格限制；请勿将普通的营销模板粘贴到此类别中。

假设验证码的有效期为五分钟：

| 设置 | 示例选择 | 原因 |
| - | - | - |
| 后端验证码有效期 | 5 分钟 | 您的服务器在此时间后将拒绝该验证码。 |
| 客户可见的过期文案 | 5 分钟 | 消息中应当描述相同的有效期。 |
| 发送有效期 | 最多 5 分钟，并预留处理时间 | 切勿故意在验证码失效后才送达。 |

当前 YCloud 模板协议支持的身份验证 `messageSendTtlSeconds` 值为 **30 至 900 秒**，新创建的身份验证模板 **默认值为 10 分钟** 。历史模板可能具有不同的默认值；请检查已保存的设置，而不要假设所有现有模板都相同。显示的过期选项支持 **1–90 分钟**，但该显示设置不会延长允许的发送有效期范围。

五分钟的 TTL 并不保证接收后还剩余整整五分钟：从验证码生成开始，时间就已经在流逝。您的应用程序应显示实际剩余的有效时间。

### 保持 Android 集成信息最新

一键认证（One-tap）和零点击认证（Zero-tap）需要匹配的应用身份和正常工作的握手逻辑。当前的 YCloud 模板契约使用 `supported_apps`；旧版的顶级 `package_name` 和 `signature_hash` 字段已被弃用。

Meta 最新的身份验证文档宣布 **2026 年 10 月 15 日** 为旧版 `PendingIntent` 握手的迁移截止日期，并推荐使用 OTP Android SDK。如果您的应用仍在使用该旧流程，请将迁移视为一项应用层任务，而不仅仅是修改模板文本。在发布前，请查阅[最新的一键和零点击认证文档](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/zero-tap-authentication-templates/)。

### 测试失败分支

测试验证码过期、二次请求验证码、输入错误验证码、设备离线、不受支持的客户端以及 Android 应用签名不匹配等场景。确定发放新验证码是否会使前一个验证码失效，并确保界面逻辑与该策略一致。

切勿根据 `delivered` 或 `read` 推断身份验证已成功。只有您的验证后端才能确定提交的验证码对目标用户和操作是否有效。

## 设计验证流程

1. 允许客户请求验证码并确认接收目标。
2. 说明验证码将通过 WhatsApp 发送。
3. 在您的验证系统中生成并校验验证码。
4. 发送带有必需参数的已获批模板。
5. 将消息送达与验证成功分开进行跟踪。
6. 在适当时提供受控的重试机制或备用路由。

对验证码请求应用速率限制和重试控制。切勿将 WhatsApp 送达或已读回执视为客户已通过身份验证的证明。

不要在通用应用程序日志中记录可用的验证码。

## 定价与可用性

身份验证消息有其专属费率，在符合条件的情况下可能会适用国际身份验证费率。请参阅 [WhatsApp 定价](/zh/documentation/whatsapp-business-platform/pricing-limits-and-quality/whatsapp-pricing)。

客户请求验证码并不意味着允许未来向其发送不相关的营销消息。请确保用户授权和消息用途与所请求的验证保持一致。

## 实施指南

* [复制验证码认证](/zh/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/copy-code-authentication)
* [一键认证](/zh/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/one-tap-authentication)
* [零点击认证](/zh/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/zero-tap-authentication)
* [使用 YCloud 发送验证码](/zh/documentation/quick-start/send-verification-codes-via-whatsapp)

有关上游行为，请参阅 Meta 的[身份验证模板](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/)。

## 常见问题

<AccordionGroup>
  <Accordion title="消息已送达，但验证码已过期。是哪个设置有误？">
    请比对三个时间点：应用程序生成验证码的时间、消息等待送达的最长时长以及客户提交验证码的时间。模板中的过期文本不会延长服务器的有效期限。请使用适合有效验证码生命周期的送达 TTL，根据安全设计废弃被替代的旧验证码，并提供受控的重新请求新验证码功能。
  </Accordion>

  <Accordion title="一键认证或零点击认证是否免去了校验验证码的需要？">
    否。这些形式改变的只是兼容应用接收或自动填充验证码的方式。您的后端仍需校验请求、验证码、有效期和尝试次数限制。消息已送达/已读或自动填充成功并不能作为验证成功的凭据。
  </Accordion>

  <Accordion title="按钮复制了验证码而不是打开我的应用。我应该排查什么？">
    请检查客户端兼容性、获批的身份验证格式以及为应用注册的包名/签名值。在不受支持的客户端上，回退为复制验证码体验属于正常现象。在认定模板有问题之前，请先在受支持的应用/客户端组合上测试该模板。
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.