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

# Enviar un código de voz

> Entregar un código de verificación mediante una llamada de voz automatizada.

## Qué es

La Voice API realiza una llamada automatizada y lee un código de verificación de 4 a 6 dígitos
al destinatario. Úselo como un canal directo de código por voz o como respaldo
cuando otro canal de verificación no esté disponible.

## Antes de empezar

* Activa Voice para tu cuenta de YCloud.
* Recopila el número de teléfono del destinatario en formato E.164.
* Genera un código de 4 a 6 dígitos de corta duración.
* Elige un idioma compatible.
* Decide si el estado llega a través de una URL de devolución de llamada o un Webhook configurado.

## Cómo funciona

1. Genere y almacene de forma segura el desafío de verificación.
2. Envíe el código a través de la API de voz.
3. Almacene el ID del registro de voz devuelto y su `externalId`.
4. Reciba actualizaciones de entrega a través del callback o Webhook.
5. Valide el código en su aplicación y caduque el desafío.

La API de voz entrega el código. Su aplicación sigue siendo responsable de la
generación de código, los límites de intentos, la caducidad y la aprobación.

## Solicitud

`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"
  }'
```

Usa un `externalId` opaco que ayude a tu sistema a correlacionar la entrega
sin exponer el código de verificación.

## Respuesta

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

La respuesta confirma que YCloud aceptó la solicitud de voz. Esto no significa
que el destinatario haya respondido la llamada o escuchado el código completo.

## Estado de entrega

Utilice las actualizaciones de entrega o la lista de registros de voz para distinguir las llamadas aceptadas, completadas
y fallidas. Mantenga el estado de entrega separado de la aprobación de verificación:
escuchar un código no prueba que el usuario correcto lo haya enviado.

## Proteger el flujo de verificación

* Haga que los códigos expiren rápidamente.
* Limite los intentos de envío y comprobación por usuario, destino, IP y dispositivo.
* Nunca registre el código de verificación.
* Evite que un código se reutilice después de ser aprobado.
* Evite revelar si un número de teléfono pertenece a una cuenta.

## Límites y solución de problemas

* `verificationCode` debe contener de 4 a 6 dígitos.
* Los números de teléfono deben usar el formato E.164.
* La disponibilidad de idiomas puede variar según el país o la región.
* Utilice `externalId` y el ID de registro de YCloud para investigar la entrega.
* Prefiera la Verify API cuando desee que YCloud administre tanto la entrega como la comprobación
  del código como un único ciclo de vida de verificación.

<CardGroup cols={2}>
  <Card title="API de envío de código de voz" icon="volume-high" href="/api-reference/voices/send-a-voice-code">
    Inspeccione los campos de idioma, callback y respuesta.
  </Card>
</CardGroup>


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