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

# 发送语音验证码

> 通过自动语音呼叫发送验证码。

## 简介

Voice API 会拨打自动电话并读取 4 到 6 位的验证
码给接收者。您可以将其作为直接的语音验证码渠道，或者作为
其他验证渠道不可用时的备用方案。

## 开始之前

* 为您的 YCloud 账户激活语音功能。
* 收集 E.164 格式的接收者电话号码。
* 生成一个短期的 4 到 6 位数字验证码。
* 选择一种支持的语言。
* 决定状态是通过回调 URL 还是配置的 Webhook 接收。

## 工作原理

1. 生成并安全地存储验证质询。
2. 通过 Voice API 发送验证码。
3. 存储返回的语音记录 ID 和您的 `externalId`。
4. 通过回调或 Webhook 接收发送状态更新。
5. 在您的应用程序中验证验证码并使质询过期。

Voice API 负责发送验证码。您的应用程序仍需负责验证码的
生成、尝试次数限制、过期和批准。

## 请求

`POST /voices`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/voices \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+16315551111",
    "verificationCode": "123456",
    "language": "en",
    "externalId": "login-7f10b6",
    "callbackUrl": "https://example.com/webhooks/voice"
  }'
```

使用不透明的 `externalId` 帮助您的系统关联发送状态
而不会暴露验证码。

## 响应

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "VOICE_MESSAGE_ID"
}
```

该响应确认 YCloud 已接受语音请求。这并不意味着
接收者接听了电话或听到了完整的验证码。

## 递送状态

使用递送更新或列出语音记录来区分已接受、已完成
和失败的呼叫。请将递送状态与验证批准区分开来：
听到验证码并不能证明是正确的用户提交了它。

## 保护验证流程

* 让验证码快速过期。
* 限制每个用户、目标地址、IP 和设备的发送和检查尝试次数。
* 绝不记录验证码。
* 防止验证码在验证通过后被重复使用。
* 避免泄露电话号码是否属于某个账户。

## 限制与故障排除

* `verificationCode` 必须包含 4 到 6 位数字。
* 电话号码必须使用 E.164 格式。
* 语言的可用性可能因国家或地区而异。
* 使用 `externalId` 和 YCloud 记录 ID 来调查发送情况。
* 当您希望 YCloud 将发送和验证码
  检查作为一个验证生命周期进行管理时，请优先使用 Verify API。

<CardGroup cols={2}>
  <Card title="发送语音验证码 API" icon="volume-high" href="/api-reference/voices/send-a-voice-code">
    检查 language、callback 和 response 字段。
  </Card>
</CardGroup>


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