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

# 电话验证 API：OTP、短信与 WhatsApp

> Didit 电话验证支持通过短信、WhatsApp、Telegram、RCS 和语音发送 OTP 验证电话号码。每次调用 $0.02 + 运营商费用，支持运营商检测与风险评分。

Didit 的电话验证提供了一种通过一次性验证码（OTP）验证用户电话号码的可靠方法。该功能为您的身份验证流程增加了一层关键的安全保障，确保用户联系信息真实有效。

电话验证集成提示词
        将提示词复制到剪贴板



      
      

\<pre>

\````# Goal
Integrate Didit Phone Verification (OTP send + check + carrier/risk lookup) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow — the SDK collects the number and OTP for you.

1\. Add the PHONE feature to the workflow (Business Console or POST /v3/workflows/). Configure risk actions: duplicated_phone_number_action, disposable_number_action, voip_number_action.
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `phone_verifications[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server, OTP pair)
Two endpoints, paired by phone_number.

Step 1 — send the code:
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/send/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"options": {
  "code_size": 6,
  "preferred_channel": "whatsapp",
  "locale": "en-US"
},
"vendor_data": "user-1234"
}'
\```
Channels: `whatsapp` (default), `sms`, `telegram`, `voice` — delivery falls back to SMS if the preferred channel is unavailable. Codes are valid for **5 minutes**; one free retry per number within the window.
Branding: SMS codes carry your app's SMS sender name ("123456 is your verification code for Acme Bank") on every send, at no extra cost; set it in the Business Console. Pass `options.sms_sender_name` to sign one code with another name (1 to 30 characters). WhatsApp codes use a fixed message; connect your own WhatsApp Business number in the Business Console to send them under your business name.

Step 2 — check the code (user types it into your UI):
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/check/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"code": "123456",
"voip_number_action": "DECLINE"
}'
\```
Each session accepts **up to 3** code-entry attempts. The check response includes the full phone metadata (carrier, line_type, disposable, voip, ported).

\# Status enum (per phone_verifications[].status / phone.status)
"Not Started" | "In Progress" | "Approved" | "Declined" | "Failed" | "Expired or Not Found" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.PHONE)
warnings[] risk codes include:
DUPLICATED_PHONE_NUMBER, DISPOSABLE_NUMBER, VOIP_NUMBER, INVALID_PHONE_NUMBER, OTP_DELIVERY_FAILED, OTP_MAX_ATTEMPTS_REACHED, OTP_EXPIRED, PHONE_NUMBER_BLOCKED.
Full catalogue: /core-technology/phone-verification/warnings-phone-verification.

\# Failure modes to handle
\- HTTP 400 — non-E.164 phone_number on /send/.
\- send response status="Blocked" with reason="spam" — anti-abuse block; no code sent, no charge.
\- check response status="Failed" — wrong code, attempts remaining; re-prompt.
\- check response status="Declined" — third failed attempt; restart with /v3/phone/send/.
\- check response status="Expired or Not Found" — outside the 5-minute window or no pending session for that number; restart.

\# See also
\- Canonical schema: /reference/data-models#phone-verification
\- Per-feature report: /core-technology/phone-verification/report-phone-verification
\- Risk catalogue: /core-technology/phone-verification/warnings-phone-verification
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

粘贴到

在关于解读验证结果的 Academy 课程中，8:08 章节介绍了电话验证和重复检测。[电话验证与重复检测 — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=488\&rel=0\&playsinline=1)![电话验证流程图](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/phone-verification-flow.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=6c12863ce97e5ad6a11757b598918932)## 工作原理我们的电话验证解决方案通过简单易用的流程提供全面的电话号码验证。系统将 OTP 验证与高级风险评估相结合，提供大规模可靠的电话验证。**1. 收集电话号码**系统安全地收集以下信息：| 收集的数据 | 详情 |
| - | - |
| **电话号码** | 如果在创建会话时未提供，用户需以国际格式输入其电话号码。如果已提供，用户必须验证预填的号码。 |
| **国家/地区代码** | 根据 IP 地址位置自动建议或由用户自行选择。 |
| **运营商类型** | 检测是移动电话还是固定电话号码。 |**2. OTP 生成与投递**我们的验证系统：- 生成一个安全且有时效的一次性验证码
- 通过短信将验证码投递至所提供的号码
- 通过与多家运营商集成来优化投递效果
- 针对投递困难提供备用选项**3. 验证码校验**用户通过以下步骤完成验证：- 在验证界面中输入收到的验证码
- 在配置的时间范围内提交（通常为 5–10 分钟）
- 如有需要可请求新验证码（受相应的速率限制）**4. 风险评估**我们的系统执行高级检查：| 检查项 | 描述 |
| - | - |
| **格式与运营商** | 验证电话号码格式和运营商信息。 |
| **一次性号码** | 对照已知的一次性/虚拟号码数据库进行检查。 |
| **SIM 卡交换检测** | 识别潜在的 SIM 卡交换风险。 |
| **活动模式** | 检测可疑的活动模式。 |
| **历史数据** | 与历史验证数据进行交叉核对。 |**5. 结果投递**通过多种渠道获取验证结果：| 渠道 | 描述 |
| - | - |
| **仪表板** | 实时仪表板更新。 |
| **Webhook** | 即时 Webhook 通知。 |
| **API** | RESTful API 集成。 |
| **报告** | 包含详细验证信息的综合报告。 |## 验证功能我们的电话验证服务提供多项核心功能，以增强您的验证流程：#### OTP 验证- **安全代码生成**：随机生成的一次性验证码
- **SMS 投递**：快速且可靠地投递至移动设备
- **可配置的超时时间**：根据您的安全要求设置过期时间
- **重试选项**：允许用户请求新验证码，并配有恰当的速率限制
- **品牌化验证码**：SMS 验证码会指明您的品牌，而非发送通用消息，无需额外费用。参见[品牌化验证消息](#品牌化验证消息)。
- **您自己的 WhatsApp 号码**：WhatsApp 验证码可以来自您自己的 WhatsApp Business 号码。参见[通过您自己的号码发送 WhatsApp 验证码](#通过您自己的号码发送-whatsapp-验证码)。#### 品牌化验证消息SMS 验证码可以注明您的品牌，以便用户认出消息来自您：> 123456 是您用于 **Acme Bank** 的验证码仅品牌名称可自定义。
其余措辞是在各国家/地区移动运营商处登记的标准文本，可防止验证码被作为垃圾短信拦截，并且已翻译为收件人的语言。
品牌化功能是免费的：品牌化验证码与非品牌化验证码的费用相同。在 Business Console 中**设置您的 SMS 发送方名称**，路径为工作流的 **Phone Verification → Settings** 或 **White Label → SMS** 下。
它属于您的应用，而非归属于单个工作流：它会为您应用发送的每条 SMS 验证码署名，涵盖所有工作流以及通过独立 API 发送的验证码，无论是否开启白标自定义。**验证码采用哪个名称**，遵循首个匹配优先原则：1) [`POST /v3/phone/send/`](https://docs.didit.me/zh/standalone-apis/phone-send) 上的 `options.sms_sender_name`，针对该单条验证码生效。
2) 您的应用的 SMS 发送方名称。
3) 仅在白标发送时（包含白标自定义的工作流，或在 API 上设置了 `options.use_white_label_customization: true`），使用您的白标公开名称。
4) 否则，验证码发送时不带名称。发送方名称长度为 1 到 30 个字符：仅限字母、数字、空格和 ' & - !，且不能全为数字，单词之间使用单个空格。
若名称超出这些规则，API 将在发送任何验证码之前拒绝并返回 `400`。- **渠道**：该名称会添加到 SMS 消息中，包括作为其他渠道备选方案而发送的 SMS。WhatsApp 验证码使用固定文本发送，不携带该名称；若希望在其上显示您的企业名称，请[通过您自己的号码发送](#通过您自己的号码发送-whatsapp-验证码)。
- **每日变更次数**：每个应用每天（UTC 时间）最多可以开始使用两个新名称，同时计入新的发送方名称和新的 `sms_sender_name` 值。达到上限后，验证码将保留应用当前的名称直至次日，且按请求传入的新名称将以应用的当前名称发送。您之前使用过的名称不会重复计入。
- **投递优先**：品牌化问题绝不会阻断验证码发送。如果无法应用某个名称，验证码将使用应用的名称发送，或者不带名称发送。#### 编写您自己的 SMS 文本和发送方 ID您可以替换 SMS 验证码的文本以及用户看到的发送方。
在 Business Console 的 **White Label → SMS** 下配置这两项。
与 SMS 发送方名称一样，它们归属于您的应用，并适用于其发送的每条 SMS 验证码，涵盖所有工作流以及通过独立 API 发送的验证码。**您自己的文本**按语言分别编写。
当您为发送验证码所用的语言编写了文本时，验证码将采用您的文本发送；所有其他语言则保留 Didit 的翻译文本。
使用 `{code}` 表示验证码，可选择使用 `{brand}` 表示您的 SMS 发送方名称，例如 `Acme: {code} is your login code for {brand}.`文本必须满足以下要求：- 包含 `{code}` 且仅出现一次，不得包含除 `{code}` 和 `{brand}` 之外的任何占位符；
- 不得包含链接：运营商会拦截携带链接的验证码；
- 在包含 8 位验证码和 30 个字符名称的情况下，可容纳于单条 SMS 中：最多 160 个字符，若包含基本拉丁字母以外的字符（例如西里尔字母、阿拉伯字母或表情符号），则最多 70 个字符。**您自己的发送方 ID** 长度为 3 到 11 个字符，仅使用字母、数字和空格，且不能全为数字，例如 `AcmeBank`。
它会在 Didit 启用了自定义发送方 ID 的国家/地区使用，这些国家/地区的运营商无需预先登记即可接受发送方名称；在所有其他国家/地区，您的验证码将以 Didit 的发送方发出。
如需申请需要登记发送方的国家/地区，请联系支持团队。- **投递优先**：当验证码在无法承载您的文本或发送方 ID 的路由上重试发送时，它将采用 Didit 的文本发送，并附带您的 SMS 发送方名称及 Didit 的发送方，以确保验证码始终能成功送达。#### 通过您自己的号码发送 WhatsApp 验证码默认情况下，WhatsApp 验证码来自 Didit 的 WhatsApp Business 号码。
您可以改为连接您自己的 WhatsApp Business 号码，以便用户接收来自您的企业名称和号码的验证码。在 Business Console 中**连接号码**，路径为工作流的 **Phone Verification → Settings → WhatsApp number**，然后选择 **Connect WhatsApp number**。
系统会打开登录窗口：登录管理您 WhatsApp Business 号码的企业账户，然后选择 WhatsApp Business 账户及用于发送的号码。
随后，Didit 会登记该号码用于发送，并创建其验证消息。
编辑该验证消息需要具备与编辑 SMS 发送方名称相同的自定义配置编辑权限。该号码属于您的应用，而非归属于单个工作流：连接成功后，它将发送该应用发送的每一条 WhatsApp 验证码，涵盖所有工作流以及通过独立 API 发送的验证码。- **批准**：新的验证消息需要获得批准后该号码才能发送验证码，通常在几分钟内完成。在此之前，卡片会显示该号码处于等待批准状态，期间验证码将继续通过 Didit 的号码发出。
- **消息文本**：WhatsApp 上的验证消息使用您用户对应语言的标准文本：包含验证码、安全提示和复制按钮。该文本无法编辑，但发送方显示为您的企业。
- **投递**：若验证码无法在 WhatsApp 上投递，将通过 SMS 发送，并以您的 SMS 发送方名称署名。
- **计费**：您的号码发送的消息费用将计入您的 WhatsApp Business 账户，因此 Didit 仅对这些验证码收取验证费（\$0.02）。通过 SMS 发送的验证码则照常计费。
- **需要处理**：若该号码无法继续发送（例如其访问权限已从您的企业账户中移除），验证码将重新通过 Didit 的号码发出，卡片会提示您重新连接该号码。
- 可随时在同一卡片中**断开**。验证码将重新通过 Didit 的号码发出；该号码及其验证消息将保留在您的 WhatsApp Business 账户中。#### 电话号码分析- **格式验证**：确保电话号码符合正确的国际格式
- **运营商检测**：识别与该号码关联的电信运营商
- **号码类型**：区分移动电话、座机和 VoIP 号码
- **国家/地区验证**：核验电话号码是否符合预期的国家/地区格式#### 风险评估- **临时号码检测**：识别用于逃避追踪的临时号码
- **虚拟号码识别**：标记可能属于虚拟或基于 VoIP 的号码
- **活动监控**：追踪多次验证尝试中的可疑模式
- **黑名单检查**：对照内部曾被滥用的号码名单进行核对## 定价电话验证按**每条已发送消息**计费，采用透明的按量付费模式：| 组成部分 | 费用 |
| - | - |
| **Didit 费用** | 每次验证 \$0.02 |
| **运营商费用** | 因国家/地区和渠道而异 |
| **总计** | \$0.02 + 运营商费用 |您的套餐折扣仅适用于 \$0.02 的 Didit 费用；运营商费用按成本直接转嫁，不享受任何折扣。请参阅[折扣](https://docs.didit.me/zh/getting-started/pricing.md#折扣)。我们支持多种投递渠道，费用各不相同（可用性因国家/地区而异）：| 渠道 | 描述 |
| - | - |
| **短信** | 传统文本短信投递 |
| **WhatsApp** | 通过 WhatsApp 消息投递 |
| **Telegram** | 通过 Telegram 消息投递 |
| **RCS** | 富通信服务（RCS）消息投递 |
| **Viber** | 通过 Viber 消息投递 |
| **Zalo** | 通过 Zalo 消息投递（越南） |> [!NOTE]
>
> 您仅需在消息发送时付费。如果用户在一次性验证码投递前放弃，则不会对您收费。→ [电话验证定价](https://docs.didit.me/zh/getting-started/phone-verification-pricing.md)


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