> ## 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 um código por voz

> Entregue um código de verificação por meio de uma chamada de voz automatizada.

## O que é

A API de voz realiza uma chamada automatizada e lê um código de verificação de 4 a 6 dígitos
ao destinatário. Use-a como um canal direto de código por voz ou como fallback
quando outro canal de verificação estiver indisponível.

## Antes de começar

* Ative a API de voz na sua conta YCloud.
* Colete o número de telefone do destinatário no formato E.164.
* Gere um código de 4 a 6 dígitos com curta duração.
* Escolha um idioma suportado.
* Decida se o status chega através de uma URL de callback ou webhook configurado.

## Como funciona

1. Gere e armazene o desafio de verificação com segurança.
2. Envie o código através da API de voz.
3. Armazene o ID do registro de voz retornado e seu `externalId`.
4. Receba atualizações de entrega através do callback ou do webhook.
5. Valide o código na sua aplicação e expire o desafio.

A API de voz entrega o código. Sua aplicação continua responsável pela geração
do código, limites de tentativas, expiração e aprovação.

## Requisição

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

Use um `externalId` opaco que ajude seu sistema a correlacionar a entrega
sem expor o código de verificação.

## Resposta

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

A resposta confirma que a YCloud aceitou a requisição de voz. Ela não significa
que o destinatário atendeu à chamada ou ouviu o código completo.

## Status de entrega

Use as atualizações de entrega ou liste os registros de voz para distinguir chamadas aceitas,
concluídas e com falha. Mantenha o status de entrega separado da aprovação de verificação:
ouvir um código não prova que o usuário correto o enviou.

## Proteja o fluxo de verificação

* Expire os códigos rapidamente.
* Limite as tentativas de envio e verificação por usuário, destino, IP e dispositivo.
* Nunca registre o código de verificação em logs.
* Impeça a reutilização de um código após a aprovação.
* Evite revelar se um número de telefone pertence a uma conta.

## Limites e solução de problemas

* `verificationCode` deve conter de 4 a 6 dígitos.
* Os números de telefone devem usar o formato E.164.
* A disponibilidade de idioma pode variar por país ou região.
* Use `externalId` e o ID do registro na YCloud para investigar a entrega.
* Prefira a API de verificação quando quiser que a YCloud gerencie tanto a entrega quanto a
  verificação do código como um único ciclo de vida.

<CardGroup cols={2}>
  <Card title="API para enviar código por voz" icon="volume-high" href="/api-reference/voices/send-a-voice-code">
    Inspecione os campos de idioma, callback e resposta.
  </Card>
</CardGroup>


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