Como enviar áudio pela API.

Use POST /send/media, informe type: "audio" e escolha ptt: true para mensagem de voz ou false para arquivo de áudio. O campo file aceita URL HTTPS, data URI ou base64.

Exemplo completo com MP3

curl -X POST \
  -H 'token: SUA_CREDENCIAL' \
  -H 'content-type: application/json' \
  -H 'idempotency-key: audio-pedido-456' \
  -d '{
    "number":"5521999999999",
    "type":"audio",
    "file":"https://exemplo.com/audio.mp3",
    "mimetype":"audio/mpeg",
    "ptt":true
  }' \
  https://relya.com.br/send/media

O número deve incluir país e DDD, apenas com dígitos. A credencial identifica o número conectado. A chave de idempotência deve permanecer igual se seu sistema repetir a mesma ação depois de timeout ou perda de resposta.

Mensagem de voz ou arquivo de áudio?

PTT significa “push to talk”. Ele muda a apresentação, não transforma conteúdo ruim em mensagem de voz válida. O arquivo ainda precisa estar em formato aceito e acessível.

URL HTTPS, data URI ou base64

URL HTTPS

É a opção mais leve para o request. A API busca o arquivo no endereço informado. A URL precisa responder durante o processamento, usar HTTPS e entregar o conteúdo correto. Links temporários devem durar mais que o tempo de fila.

Data URI

Inclui tipo e dados no mesmo campo, por exemplo data:audio/mpeg;base64,.... É útil para arquivos pequenos e integrações que já possuem o conteúdo em memória.

Base64 puro

Evita hospedagem externa, mas aumenta o tamanho do JSON em cerca de um terço e exige mais memória. Para áudios grandes, prefira URL temporária protegida e com validade suficiente.

MIME type para MP3 e OGG

• MP3: audio/mpeg
• OGG: audio/ogg

A extensão do nome não é prova do conteúdo. Um arquivo chamado audio.mp3 pode ter outro codec. Quando houver falha de mídia, valide o MIME real, tente reproduzir o arquivo e confirme que a URL não devolve HTML de login ou erro.

{
  "number": "5521999999999",
  "type": "audio",
  "file": "https://exemplo.com/mensagem.ogg",
  "mimetype": "audio/ogg",
  "ptt": true
}

Como saber se o áudio chegou?

O 202 inicial apenas confirma que a operação foi aceita ou enfileirada. Guarde o identificador retornado e acompanhe os eventos por webhook. Seu sistema deve distinguir pelo menos:

• enfileirada: aguardando processamento;
• enviada: saiu da sessão;
• entregue: houve confirmação de entrega;
• lida: houve confirmação de leitura quando disponível;
• falha: o envio não concluiu e deve ser investigado.

Não marque uma cobrança, atendimento ou pedido como concluído apenas porque o request respondeu 202.

Erros comuns e diagnóstico

Checklist de implementação

1. Valide o número no formato internacional.
2. Defina type: "audio".
3. Escolha ptt conscientemente.
4. Informe MIME compatível com o arquivo real.
5. Use uma chave de idempotência ligada ao evento de negócio.
6. Garanta que a URL sobreviva ao tempo da fila e das tentativas.
7. Trate 202 como entrada, não entrega.
8. Confirme estado final por webhook.

Para outros formatos, veja o guia completo e a documentação das rotas.