URLs de áudio
A plataforma não recebe o arquivo de áudio. Ela recebe a URL e busca o arquivo quando precisa.
Isso vale para as duas unidades de áudio:
- A gravação da ligação —
urlAudiona raiz do payload de voz. - A mensagem de voz —
urlAudiodentro de uma mensagem, no WhatsApp. Uma conversa pode ter várias, intercaladas com texto.
As regras
| Regra | Motivo |
|---|---|
https obrigatório | O servidor da plataforma é quem faz a requisição. |
| Host por nome, nunca IP literal | https://10.0.0.5/a.mp3 e https://200.1.2.3/a.mp3 são recusados — mesmo o IP público. URL de gravação legítima usa nome. |
| Hosts locais recusados | localhost, metadata, metadata.google.internal e afins. |
| A URL termina na extensão do arquivo | .mp3, .wav, .m4a, .ogg, .opus, .flac, .webm. |
| Até 25 MB por arquivo | Limite do serviço de transcrição. Arquivo maior é recusado no download. |
| Até 50 áudios por conversa | Acima disso a ingestão inteira é recusada com 400. |
| Acessível pelo servidor da plataforma | URL que exige login interativo não funciona. |
| Válida por muito tempo | Ver a seção abaixo — é a regra que mais causa problema. |
Extensões aceitas
mp3 · wav · m4a · ogg · opus · flac · webm
É o que WhatsApp e discadores entregam. Query string depois da extensão é aceita, o que permite URL assinada:
https://midia.parceiro.com.br/wa/000519/m-1.ogg?token=abc123&expires=...
O que não passa é caminho sem extensão — comum em URL de download por id:
https://api.parceiro.com.br/midia/download?id=98213 ← recusada
Se o seu storage entrega assim, você precisa de uma rota que termine na extensão. Um redirect de
/download?id=X para o arquivo .ogg não resolve: a validação olha a URL que você mandou.
A URL precisa durar meses, não minutos
Esta é a regra que mais quebra integração, e o motivo é que ela não é intuitiva.
A URL não serve só para transcrever. Ela sustenta:
- A transcrição, que pode não acontecer na hora — se o cliente atingiu o limite de uso, a conversa espera na fila até ele liberar. Ver Limite de uso.
- O player na tela do supervisor, durante toda a retenção contratada — que é medida em meses. Quando o supervisor quer conferir se a MAIA leu certo, ele ouve o áudio.
- O reprocessamento, se o cliente recalibrar o roteiro e quiser reauditar conversas antigas.
Uma URL que expira em uma hora vai funcionar no teste de integração e falhar em produção: o player do supervisor mostra erro, e a auditoria perde a evidência primária.
Se você usa URL assinada, use validade longa — meses. Se a sua política de segurança não permite, converse com o time do QA Analytics antes de integrar áudio.
Prefira, em ordem:
- URL estável e pública no seu CDN de mídia. Simples, e não expira.
- URL assinada com validade longa (meses).
- URL assinada de curta duração — não funciona.
Segurança: por que as regras são estritas
Vale entender, porque explica recusas que parecem arbitrárias.
Quando você informa uma URL e o nosso servidor a busca, você está escolhendo um endereço que o nosso
servidor vai acessar. Uma URL apontando para 169.254.169.254 (serviço de metadados de nuvem) ou para
um banco de dados interno faria o servidor ler o que ninguém deveria.
Por isso:
- IP literal é sempre recusado, mesmo público: quem manda IP cru está pulando o DNS, e é aí que mora o endereço interno.
- O endereço é conferido duas vezes: o texto da URL na ingestão (recusa cedo, com mensagem legível), e o IP resolvido no momento do download. A segunda é a que protege de verdade, porque só ela vê para onde o nome aponta naquele instante.
- O tipo do arquivo é conferido no download, não só pela extensão. A extensão é o primeiro filtro, barato, contra o caso óbvio.
Nada disso exige ação sua além de usar URLs normais de mídia. Se você recebe uma recusa que não entende, a mensagem diz qual regra quebrou — ela é escrita para ser lida por quem integra, não por quem escreveu o código.
Áudio e transcrição
O que acontece com cada mensagem, e o que a plataforma cobra do cliente:
| A mensagem tem | O que a plataforma faz |
|---|---|
Só texto | Nada de áudio. Segue direto para a análise. |
Só urlAudio | Baixa e transcreve. Cobrado por minuto de áudio. |
texto e urlAudio | Usa o texto — não transcreve por cima. A URL fica para o player. |
Se você já tem a transcrição, mande-a: é mais barato para o cliente e mais fiel, porque a origem costuma ter contexto que um transcritor genérico não tem.
A conversa só entra na análise com todos os áudios em texto. Sentimento e auditoria leem o todo, e um áudio faltando no meio muda o julgamento. Se um áudio falhar, os já transcritos são preservados: o reprocessamento retoma só o que falta, e o cliente não paga duas vezes pelo mesmo arquivo.
Erros
| Mensagem | Causa |
|---|---|
URL do áudio vazia. | Campo presente mas em branco. |
URL do áudio inválida: '...'. | Não é URL absoluta. |
URL do áudio precisa ser https. | Esquema http. |
URL do áudio aponta para um host local: '...'. | localhost, metadata etc. |
URL do áudio precisa apontar para um nome, não para um IP. | Host numérico. |
URL do áudio precisa terminar com a extensão do arquivo. | Caminho sem extensão. |
Extensão de áudio não permitida: 'xyz'. Aceitas: ... | Formato fora da lista. |
Conversa com mais de 50 áudios não é aceita numa ingestão só. | Teto por conversa. |
Todos são 400 e não devem ser retentados sem correção. Ver Erros e retry.