Pular para o conteúdo principal

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 — urlAudio na raiz do payload de voz.
  • A mensagem de voz — urlAudio dentro de uma mensagem, no WhatsApp. Uma conversa pode ter várias, intercaladas com texto.

As regras​

RegraMotivo
https obrigatórioO servidor da plataforma é quem faz a requisição.
Host por nome, nunca IP literalhttps://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 recusadoslocalhost, 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 arquivoLimite do serviço de transcrição. Arquivo maior é recusado no download.
Até 50 áudios por conversaAcima disso a ingestão inteira é recusada com 400.
Acessível pelo servidor da plataformaURL que exige login interativo não funciona.
Válida por muito tempoVer 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:

  1. 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.
  2. 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.
  3. O reprocessamento, se o cliente recalibrar o roteiro e quiser reauditar conversas antigas.
URL assinada de curta duração quebra o produto

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:

  1. URL estável e pública no seu CDN de mídia. Simples, e não expira.
  2. URL assinada com validade longa (meses).
  3. 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 temO que a plataforma faz
Só textoNada de áudio. Segue direto para a análise.
Só urlAudioBaixa e transcreve. Cobrado por minuto de áudio.
texto e urlAudioUsa 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​

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