Enviar um código por voz

​

O que é

​

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.

​

Requisição

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

​

Resposta

{
  "id": "VOICE_MESSAGE_ID"
}

​

Status de entrega

​

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.