Baixar mídia na WhatsApp Cloud API: áudio e imagem passo a passo

Baixar mídia na WhatsApp Cloud API: áudio e imagem passo a passo

Para baixar mídia na WhatsApp Cloud API, saiba que o webhook entrega apenas o ID da mídia, não o arquivo. Com esse ID, você consulta o endpoint de mídia usando o token de acesso, recebe uma URL temporária e baixa o binário com o mesmo token antes que o link expire. Depois, o arquivo deve ir para um armazenamento privado, e só então uma cópia segue para transcrição ou análise.

Principais pontos

• O webhook traz o ID da mídia e o tipo (áudio, imagem), nunca o conteúdo em si.
• O download tem duas chamadas: uma para obter a URL temporária e outra para baixar o arquivo, ambas autenticadas.
• A URL expira em poucos minutos, então o download deve ser imediato e, se falhar, o fluxo pede uma URL nova com o mesmo ID.
• Guarde o arquivo em armazenamento privado, com retenção definida, e não dependa da cópia que fica com a Meta.
• Transcrição e análise de imagem devem receber só o necessário, com registro do que foi enviado e para onde.

O que chega no webhook quando alguém envia áudio ou imagem?

Quando um cliente manda uma mensagem de voz ou uma foto, a Cloud API chama o seu endpoint de webhook com um evento de mensagem. Nesse evento há o identificador da mensagem, o número de quem enviou, o tipo e um objeto com os dados da mídia. Esse objeto contém o ID da mídia e o tipo MIME. Em imagens, pode haver também uma legenda escrita pelo cliente.

O ponto que mais confunde quem começa é este: não existe link de arquivo no evento. O ID é só uma referência. Para chegar ao arquivo, você precisa fazer chamadas à API, e elas exigem o token de acesso da sua conta. Os formatos aceitos e os limites de tamanho mudam com o tipo de mídia, então confira a documentação oficial de mídia da Cloud API em vez de fixar valores no código.

Antes de qualquer download, valide a assinatura do webhook. A Meta envia um cabeçalho com assinatura calculada a partir do segredo do aplicativo, e o seu servidor deve recalculá-la e comparar. Sem isso, qualquer pessoa que descubra a URL do seu webhook pode forçar o seu sistema a baixar arquivos arbitrários. O guia de webhooks da Stripe é um bom exemplo geral de como pensar verificação de assinatura e reentregas, mesmo sendo de outro provedor.

Passo a passo para baixar a mídia

O fluxo mínimo e confiável tem estas etapas:

• Passo 1: receba o webhook, valide a assinatura e responda com sucesso o mais rápido possível, sem fazer o download dentro dessa requisição.
• Passo 2: grave o evento em uma fila com o identificador da mensagem. Esse identificador serve de chave de idempotência, porque o mesmo evento pode chegar mais de uma vez.
• Passo 3: um worker lê a fila e consulta o endpoint de mídia da Graph API com o ID da mídia, enviando o token no cabeçalho de autorização.
• Passo 4: a resposta traz a URL temporária, o tipo MIME, o tamanho e um hash do arquivo. Guarde esses metadados.
• Passo 5: baixe o binário nessa URL, enviando de novo o token no cabeçalho de autorização. Sem ele, o download é recusado.
• Passo 6: confira se o tamanho e o hash batem com os metadados. Se não baterem, descarte e tente de novo.
• Passo 7: grave o arquivo no armazenamento privado e registre o caminho, o hash e a data no banco de dados.
• Passo 8: só depois de gravado, marque a mensagem como pronta para a próxima etapa (transcrição ou análise).

Separe bem a resposta do webhook do trabalho pesado. Se o seu endpoint tenta baixar, transcrever e responder ao cliente dentro da mesma requisição, qualquer lentidão gera reentrega do evento e você processa a mesma mensagem duas vezes. A fila resolve isso. Se você usa n8n, o artigo sobre como montar um fluxo de atendimento com n8n e a Cloud API mostra a estrutura geral de recepção e processamento.

Como tratar link expirado e falhas de download?

A URL de download é temporária por desenho. Ela serve para uma busca imediata, não para ser guardada e usada depois. O erro mais comum em projetos novos é salvar essa URL no banco e tentar abri-la horas depois, quando um atendente clica para ver a foto.

A regra prática é simples: nunca persista a URL, persista o arquivo. Se o download falhar ou o link tiver expirado, o worker volta ao passo 3 e consulta o ID de novo para obter uma URL nova. Isso funciona enquanto a mídia ainda estiver disponível do lado da Meta, que a mantém por um período limitado. Passado esse tempo, o ID deixa de resolver e o arquivo se perde se você não o tiver guardado.

Uma política de tentativas razoável:

• Tente de novo em caso de erro de rede ou resposta temporária do servidor, com espera crescente entre tentativas.
• Em caso de URL expirada, peça uma nova antes de repetir o download.
• Em caso de erro de autenticação, não repita sem parar: alerte, porque o token provavelmente venceu ou perdeu permissão.
• Defina um número máximo de tentativas e mova a mensagem para uma fila de falhas, visível para uma pessoa.
• Se a mídia não puder ser recuperada, avise o cliente de forma simples e peça que reenvie, em vez de fingir que processou.

O artigo sobre erros e retentativas no n8n detalha esse raciocínio para fluxos de IA, e ele vale também fora do n8n.

Onde armazenar o arquivo e por quanto tempo?

Um arquivo de WhatsApp costuma ser dado pessoal: a voz de alguém, o rosto, um documento fotografado, uma receita, um endereço visível ao fundo. Trate-o assim desde o primeiro dia.

O desenho básico é um armazenamento de objetos privado (qualquer serviço compatível com o padrão de buckets), sem acesso público e com links assinados de curta duração quando uma pessoa precisar abrir o arquivo. Nomeie o objeto pelo identificador da mensagem, não pelo telefone do cliente. No banco, guarde só os metadados: identificador, tipo, hash, caminho, data de recebimento, situação do processamento e prazo de exclusão.

Defina a retenção antes de ligar o fluxo. Pergunte qual é a finalidade do arquivo: se o áudio só serve para gerar o texto, talvez o texto baste e o áudio possa ser apagado depois de conferido. Se a foto é evidência de um atendimento, o prazo vem da regra do processo, não da conveniência técnica. Para a LGPD, o que importa é ter finalidade clara, coletar o mínimo e conseguir apagar quando o prazo acabar. A ANPD é a referência oficial para orientações.

Por fim, registre quem acessa o quê. Um log simples de leitura de arquivos já evita muita dor de cabeça quando alguém pergunta quem viu aquela foto.

Como encaminhar para transcrição ou análise de imagem?

Com o arquivo guardado, a etapa seguinte é transformar mídia em algo que o seu processo entenda. Para áudio, isso é transcrição. Os áudios do WhatsApp costumam chegar em um formato de áudio compacto, e muitos serviços de transcrição o aceitam direto, mas outros pedem conversão. Teste com áudios reais de clientes: ruído de rua, sotaque regional e frases cortadas pesam mais do que a escolha do modelo. O artigo sobre transcrição de áudio de WhatsApp com IA compara precisão, custo e privacidade.

Para imagem, defina o que você quer extrair antes de enviar ao modelo. Pedir uma descrição livre rende texto longo e pouco útil. Pedir campos específicos (tipo de problema visível, se a foto está legível, se há documento na imagem) rende dados que o fluxo consegue usar. Inclua sempre uma saída para foto ilegível ou fora do assunto, que encaminha para uma pessoa.

Três cuidados valem para as duas etapas:

• Trate o texto transcrito e o texto lido na imagem como conteúdo não confiável. Um cliente, ou alguém mal-intencionado, pode falar ou escrever instruções para o agente. O guia da OWASP sobre prevenção de prompt injection explica por que o conteúdo da mídia nunca deve ter autoridade para acionar ações.
• Verifique para onde o arquivo vai. Se o serviço de transcrição ou visão roda fora do Brasil, isso pode configurar transferência internacional. Veja o que a LGPD exige nesse caso antes de escolher o provedor.
• Guarde o resultado junto ao arquivo original, com a versão do modelo e a data, para poder auditar e reprocessar depois.

Cenário ilustrativo: foto e áudio de um problema

Imagine uma loja de manutenção de equipamentos que recebe, pelo WhatsApp, a foto de uma peça danificada e um áudio explicando o defeito. Este é um cenário ilustrativo, sem relação com nenhum caso real.

O webhook chega com dois eventos, um de imagem e um de áudio, cada um com seu ID de mídia. O servidor valida a assinatura, grava os dois na fila e responde de imediato. O worker baixa a foto e o áudio, confere o hash, salva ambos no armazenamento privado e registra os metadados. O áudio vai para transcrição, a foto vai para uma análise com campos fixos. O resultado é um resumo curto com o texto do cliente, o que a imagem mostra e um aviso de que a análise é automática. Um atendente revisa esse resumo, confirma ou corrige e só então o sistema responde ao cliente com o próximo passo. Se o áudio estiver ininteligível, o fluxo pede ao cliente que descreva por texto.

Nenhuma decisão de garantia ou orçamento sai da análise automática. Ela prepara o terreno, a pessoa decide.

Como aplicamos mapear, limitar, pilotar e transferir

No trabalho com empresas, começamos por mapear: quais tipos de mídia os clientes realmente mandam, em que etapa do atendimento e o que a equipe faz hoje com eles. Em seguida, limitar: definir quais tipos de arquivo o fluxo aceita, que dados saem do armazenamento, o prazo de retenção e o que o agente nunca faz sozinho, como prometer prazo ou aprovar garantia.

O piloto cobre um único fluxo real, por exemplo só os áudios de um tipo de solicitação, com logs de cada etapa (recebido, baixado, guardado, transcrito, revisado) e uma métrica de sucesso combinada de antemão. Ao final, transferimos a operação com documentação e decidimos em conjunto se vale expandir, ajustar ou parar. Para quem quer ver o método em conjunto, o artigo sobre como Juan Carlo trabalha com empresas descreve as etapas.

Checklist antes de colocar em produção

• A assinatura do webhook é validada e o endpoint responde rápido.
• O processamento é assíncrono, com fila e chave de idempotência pelo identificador da mensagem.
• O token de acesso é guardado em cofre de segredos, com rotina de renovação e alerta de falha.
• O download usa autenticação nas duas chamadas e confere tamanho e hash.
• A URL temporária nunca é salva, só o arquivo.
• O armazenamento é privado, com retenção e exclusão definidas.
• Há fila de falhas visível e um caminho de reenvio pelo cliente.
• O provedor de transcrição ou visão foi avaliado quanto a local de processamento e uso dos dados.
• O conteúdo extraído não aciona ações sem revisão ou regra explícita.
• Existe um log de quem acessou cada arquivo.

Perguntas frequentes

Preciso baixar a mídia imediatamente ou posso fazer depois? O ideal é baixar logo após o recebimento, porque a URL é temporária e a mídia fica disponível do lado da Meta por um período limitado. Se o download atrasar, você ainda pode consultar o ID para gerar uma URL nova, mas só enquanto a mídia existir. Guardar o arquivo no seu armazenamento elimina essa dependência.

Por que o download retorna erro mesmo com a URL correta? O motivo mais comum é a ausência do token de acesso no cabeçalho de autorização na segunda chamada, a do download. Outras causas são URL expirada, token vencido ou sem permissão e mídia que já saiu da retenção da Meta. Registre o código de resposta de cada tentativa para distinguir esses casos.

Posso enviar o link da mídia direto para o serviço de transcrição? Não é recomendável. A URL exige autenticação e expira, então o serviço externo provavelmente não conseguirá abri-la, e você não quer expor o seu token a terceiros. O caminho seguro é baixar o arquivo, guardá-lo e enviar o conteúdo ao serviço (ou um link assinado seu, de curta duração), depois de avaliar a questão de privacidade.

É possível transcrever sem enviar áudio para fora da empresa? Sim, com um modelo de transcrição rodando em infraestrutura própria, o que reduz a exposição de dados, em troca de mais trabalho de operação e de testes de qualidade. O artigo sobre Ollama na empresa mostra como pensar essa decisão sem improviso. Compare a qualidade com áudios reais antes de escolher.

Fontes

• Meta: referência de mídia da WhatsApp Cloud API
• Stripe: webhook delivery and verification
• OWASP: prompt injection prevention
• ANPD: Autoridade Nacional de Proteção de Dados