> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 一次性密码（OTP）

> 使用 OneSignal 发送一次性密码消息，用于双因素身份验证、账户验证和欺诈防范。涵盖 OneSignal Verify、自建验证码身份验证、专用发件人最佳实践以及受众验证。

一次性密码（OTP）消息是一条包含简短临时验证码的短信，用于验证用户的身份。用户将该验证码输入到您的应用或网站中，以证明他们能够访问其所提供的电话号码。

OTP 消息可提供：

* **账户保护：** 防止未经授权的访问，从而降低支持成本、欺诈损失和声誉损害
* **电话号码验证：** 成功送达并正确输入的 OTP 可确认该号码真实、有效，并且确实掌握在提交它的人手中
* **从入口处防范欺诈：** 在账户创建时使用 OTP，可阻止虚假注册、机器人账户和滥用行为
* **监管与合规基线：** 对于某些行业（金融、医疗），多因素身份验证是必需的。SMS OTP 是最易于使用的方法，因为它适用于每一部手机，且无需安装任何应用

常见触发场景：

* **账户创建：** 在注册过程中确认新用户的电话号码
* **登录 / 双因素身份验证：** 在密码之外增加第二层验证
* **密码重置：** 在允许更改凭据之前确认身份
* **交易确认：** 验证诸如转账或地址更改等高价值操作

***

## 同意要求

OTP 消息的同意要求与事务性消息遵循相同的标准。用户在包含披露文案的表单中输入其电话号码即构成充分的选择加入（opt-in）。披露文案必须直接显示在电话号码字段上或其附近，而不能位于单独的页面或埋藏在服务条款之中。

<Card title="必需的披露文案" icon="shield" href="./sms-opt-in-and-collection#otp-opt-ins">
  披露文案要求以及完整的 OTP 选择加入合规规则。
</Card>

***

## 如何发送 OTP 消息

使用 OneSignal 发送 OTP 消息有两种方式：

| 方法                       | 适用对象                           | 您需要管理的内容          |
| ------------------------ | ------------------------------ | ----------------- |
| **OneSignal Verify**（推荐） | 希望使用托管解决方案的团队：验证码生成、送达和验证均为您处理 | 仅需配置              |
| **自建**                   | 需要自定义验证逻辑或已拥有验证码生成系统的团队        | 验证码生成、存储、过期、限流和验证 |

***

## OneSignal Verify

<Note>
  Verify 仅向 OneSignal SMS 客户提供（不适用于 Twilio 集成）。
</Note>

<Steps>
  <Step title="创建验证服务">
    设置一个友好名称（您的品牌名称）、验证码长度以及验证码重新生成的频率。
  </Step>

  <Step title="发送验证码">
    提供用户的电话号码和渠道（`sms`）。可选择指定自定义验证码或覆盖验证码长度。

    默认情况下，发送给最终用户的消息为：*"Your \[brand name] verification code is: XXXXXX."*
  </Step>

  <Step title="检查验证码">
    提供用户的电话号码以及他们输入的验证码。API 会返回该验证码是否有效。
  </Step>
</Steps>

### 其他注意事项

* **过期时间：** 默认情况下验证码在 10 分钟后过期。如需自定义，请联系支持团队。
* **重试：** 处理失败的验证尝试，并在您的应用中实现重试逻辑。
* **安全性：** 遵循处理敏感数据（如电话号码和验证码）的最佳实践。

***

## 自建验证码身份验证

您也可以自行管理验证逻辑：在您自己的后端生成验证码、跟踪过期时间并验证尝试。采用这种方式时，您可以通过 OneSignal 的 [Create Message API](/reference/create-message) 将 OTP 消息作为标准的 API 触发短信来发送。

<Steps>
  <Step title="在您的后端生成验证码">
    通常为 4–8 位数字，过期时间窗口为 5–10 分钟。
  </Step>

  <Step title="通过 OneSignal API 发送">
    调用 Create Message 端点，提供收件人的电话号码、您的 OTP 发件人，以及包含验证码的消息正文（例如，*"Your \[brand name] verification code is 847291. It expires in 10 minutes."*）。
  </Step>

  <Step title="验证验证码">
    当用户在您的应用中提交验证码时，将其与您存储的内容进行比对。在成功验证后或过期后（以先到者为准）使该验证码失效。
  </Step>
</Steps>

### 您的职责

* 安全地生成和存储验证码
* 强制执行过期：验证码不应无限期有效
* **限流：** 限制单个电话号码在给定时间窗口内可请求的验证码数量，以防范 SMS pumping 欺诈
* **尝试次数限制：** 在达到一定的失败输入次数后（例如 3–5 次）锁定，以防范暴力破解攻击
* **重试逻辑：** 处理短信送达失败的情况

***

## 专用发件人最佳实践

虽然您可以从任何发件人发送 OTP 消息，但最佳实践是使用经批准用于身份验证用例的专用发件人。

如果您的 OTP 消息与促销或事务性消息共用同一个发件人，那么单次 STOP 退订就会导致用户无法再接收验证码，从而实际上将他们锁定在自己的账户之外。专用 OTP 发件人可将退订范围限定开来，因此营销退订绝不会阻断安全验证码。

***

## 受众验证

干净的订阅者列表对 OTP 送达率至关重要。无效或已停用的号码意味着验证码无法送达用户，这可能会阻碍账户创建、将用户锁定在密码重置流程之外，并削弱对您身份验证流程的信任。

在收集时使用 Lookup 验证电话号码，仅收集您拥有已批准发件人资源的地区的号码，并以 E.164 格式存储所有号码（例如 `+14155551234`）。

<Card title="受众验证" icon="circle-check" href="./sms-opt-in-and-collection#audience-validation">
  关于 Lookup、地区限制、所有权验证和 E.164 格式的完整详情。
</Card>

***

## 常见问题

### OneSignal Verify 与自建 OTP 有什么区别？

OneSignal Verify 为您处理验证码生成、送达和验证。您只需管理配置。自建则让您对验证逻辑拥有更多控制权，但您需要负责验证码生成、存储、过期、限流和重试处理。OneSignal Verify 仅向 OneSignal SMS 客户提供（不适用于 Twilio 集成）。

### 使用 OneSignal Verify 时验证码的有效期有多长？

默认情况下验证码在 10 分钟后过期。如需自定义过期时间窗口，请联系 OneSignal 支持团队。

### 为什么我的 OTP 需要专用发件人？

如果用户向一个同时处理 OTP 和其他消息类型的发件人发送 STOP，他们将退订来自该发件人的所有消息，包括验证码。这可能会将他们锁定在自己的账户之外。专用 OTP 发件人可将退订范围干净利落地限定开来。

### 如果 OTP 送达失败会怎样？

使用 OneSignal Verify 时，如果您发现大范围的送达失败，请联系支持团队。如果您是自建，请在您的后端实现重试逻辑，并在 Audience Activity 中监控错误码。有关错误码故障排查，请参阅 [SMS 消息报告](./sms-message-reports#understanding-sms-failures)。

### 我可以将 OTP 消息用于账户创建验证吗？

可以。这是最常见的用例之一：在注册过程中发送验证码，以确认用户拥有其所提供的电话号码。在此阶段，Lookup 也可以帮助在发送前验证号码。

***

## 相关页面

<Columns cols={2}>
  <Card title="SMS 选择加入与收集" icon="user-plus" href="./sms-opt-in-and-collection">
    适用于所有项目类型的收集方法、必需的披露文案和受众验证。
  </Card>

  <Card title="事务性消息" icon="receipt" href="./sms-transactional-messaging">
    与 OTP 项目并行的事务性用例和收集点。
  </Card>

  <Card title="SMS 消息报告" icon="chart-line" href="./sms-message-reports">
    用于排查 OTP 失败问题的送达指标和 SMS 错误码。
  </Card>

  <Card title="Create Message API" icon="code" href="/reference/create-message">
    用于从您的后端触发 OTP 和事务性发送的 API 参考。
  </Card>
</Columns>