> ## 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 цифр. Используйте его как основной канал голосового кода или как запасной, когда другой канал верификации недоступен.

## Перед началом

* Активируйте Voice для вашего аккаунта YCloud.
* Соберите номер телефона получателя в формате E.164.
* Сгенерируйте короткоживущий код из 4–6 цифр.
* Выберите поддерживаемый язык.
* Определите, будет ли статус приходить через callback URL или настроенный вебхук.

## Как это работает

1. Сгенерируйте и безопасно сохраните вызов на верификацию.
2. Отправьте код через Voice API.
3. Сохраните возвращённый ID голосовой записи и ваш `externalId`.
4. Получайте обновления доставки через callback или вебхук.
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` и ID записи YCloud для расследования доставки.
* Предпочитайте Verify API, когда хотите, чтобы YCloud управлял и доставкой, и проверкой кода в рамках единого жизненного цикла верификации.

<CardGroup cols={2}>
  <Card title="API отправки голосового кода" icon="volume-high" href="/api-reference/voices/send-a-voice-code">
    Изучите поля языка, callback и ответа.
  </Card>
</CardGroup>


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