Mídias recebidas no WhatsApp Cloud API: download seguro, expiração e retenção

Para receber arquivos pelo WhatsApp Cloud API, trate o webhook como aviso de uma mídia que precisa ser recuperada. Seu servidor usa o identificador recebido para consultar uma URL temporária e faz o download autenticado. Depois, guarda a cópia em armazenamento privado, com acesso controlado e prazo de retenção definido pela operação.

Não use a URL temporária como endereço permanente de um anexo no CRM. A coleção oficial da Meta informa validade de cinco minutos para essa URL. Esse relógio é diferente da disponibilidade da mídia no provedor e do prazo pelo qual sua empresa decide manter uma cópia. Separar os três evita anexos quebrados e arquivos esquecidos.

Resumo rápido

• Receba o evento, valide a origem e registre o trabalho em uma fila durável.
• Guarde identificadores do evento e da mídia, sem transformar a URL temporária em arquivo definitivo.
• Consulte a URL perto do momento do download e use autenticação no servidor.
• Verifique o arquivo antes de liberar OCR, transcrição ou abertura pelo atendente.
• Defina retenção também para derivados, cópias de segurança e registros operacionais.

Separar evento, identificador, URL e arquivo

Uma integração confiável mantém identidades distintas para a mensagem, a mídia no provedor e o objeto salvo pela empresa. O identificador da mensagem ajuda a reconhecer entregas repetidas. O da mídia permite solicitar acesso ao conteúdo. A URL temporária viabiliza a transferência. O endereço interno aponta para a cópia sob controle da empresa.

A coleção oficial de mídia da Meta separa as operações: consultar a URL com GET /{media-ID}, baixar com GET /{media-URL} e excluir com DELETE /{media-ID}. Essas operações não substituem o armazenamento da sua aplicação.

Defina estados explícitos no banco: recebido, aguardando download, em quarentena, disponível, falhou e excluído. Assim, o atendente consegue distinguir arquivo em análise de anexo perdido. Cada transição deve registrar horário e motivo, sem despejar o documento ou a credencial nos logs.

Receber o webhook sem perder nem duplicar trabalho

Antes de enfileirar, valide a autenticidade conforme a configuração oficial de webhooks da Graph API. Não confunda o segredo usado na configuração do endpoint com a credencial de download. Centralize a verificação em um componente testável e preserve o corpo original necessário à validação.

Uma boa arquitetura confirma o recebimento depois de gravar o evento de forma durável, deixando o download para um trabalhador separado. Essa é uma recomendação de projeto: se o processo cair após responder ao webhook, o trabalho já estará registrado. Se a gravação falhar, o evento não deve desaparecer como se estivesse concluído.

Crie uma chave única que inclua a conta atendida e o identificador da mensagem. Isso impede que uma entrega repetida gere vários anexos ou várias transcrições. Em sistemas com múltiplas empresas, inclua a organização na chave. Um identificador externo sozinho não substitui o isolamento entre clientes.

O evento pode conter conteúdos diferentes do tipo esperado. Confira a estrutura antes de acessar campos de mídia. Mensagens de texto e atualizações de status precisam seguir seu próprio caminho. Dados incompletos devem virar uma falha observável, com informação suficiente para diagnóstico e sem expor a conversa inteira.

Imponha limites de tamanho no recebimento e na fila. Defina quem atende o alerta quando a fila acumula. O número de eventos aceitos não mede sucesso por si só: acompanhe também quantos chegaram ao estado disponível e quantos precisam de ação humana.

Baixar com autenticação e lidar com a expiração

A referência oficial de recuperação da URL informa que a URL vale por cinco minutos e exige token para o download. Ela também documenta o parâmetro opcional phone_number_id, que permite verificar a associação da mídia ao número indicado. Consulte a URL imediatamente antes da transferência.

Mantenha a credencial no servidor, em armazenamento de segredos, com permissões adequadas. Não envie o token ao navegador, não monte links com ele em parâmetros de consulta e não registre cabeçalhos de autenticação. A coleção de mídia relaciona a permissão whatsapp_business_messaging ao uso dos endpoints.

evento validado
  → registro único da mensagem
  → fila de recuperação
  → consulta autenticada pelo identificador da mídia
  → download autenticado da URL recém-obtida
  → quarentena e validação
  → cópia privada liberada para a operação

Se a transferência falhar após uma espera, obtenha outra URL antes de repetir. Evite tentar indefinidamente a mesma URL expirada. Limite tentativas, aplique espera progressiva em falhas transitórias e registre a causa. Falha de credencial pede correção de acesso; arquivo indisponível pode exigir contato com o remetente. Esses casos não devem compartilhar uma mensagem genérica de erro.

Configure tempo máximo de conexão e transferência. Faça o download com limite de bytes durante a leitura, mesmo quando houver um tamanho anunciado. Uma biblioteca que carrega tudo na memória pode derrubar o processo antes de o aplicativo verificar o arquivo. Salve primeiro em área temporária protegida e só promova o objeto após as validações.

A URL deve vir da resposta da API, com verificação de transporte e destino conforme a política do seu cliente HTTP. Não aceite um endereço arbitrário enviado no campo de texto pelo usuário como se fosse a mídia oficial. Também não encaminhe credenciais automaticamente para qualquer destino de redirecionamento.

Validar o arquivo antes de usar IA

Considere todo anexo recebido uma entrada não confiável. Use uma lista de formatos aceitos pela operação, confira o tipo real do conteúdo e gere um nome interno independente do nome enviado. Um arquivo chamado “comprovante.pdf” não deve ser aprovado apenas pela extensão. Um nome também pode carregar caracteres problemáticos para caminhos e telas.

Mantenha os objetos recebidos em quarentena enquanto executa as verificações previstas. O resultado deve ser registrado como aprovado, rejeitado ou inconclusivo. Se a ferramenta de análise estiver indisponível, não transforme a ausência de verificação em aprovação silenciosa. A operação precisa de uma fila para tratar essa exceção.

Antes de encaminhar para OCR ou transcrição, confira a finalidade e a necessidade dos dados. O guia de mascaramento de dados pessoais antes de APIs externas ajuda a reduzir exposição em etapas posteriores. Nem todo arquivo precisa ser enviado a um modelo: o atendente pode precisar apenas de uma confirmação de recebimento.

Texto extraído do arquivo continua sendo conteúdo do remetente. Instruções encontradas em um PDF não devem alterar permissões do assistente, disparar mensagens ou liberar acesso ao CRM. Separe a extração de informação das ações de negócio e exija validação dos campos que produzirem consequências operacionais.

Exemplo: oficina de bicicletas em Curitiba

Imagine uma oficina em Curitiba que recebe fotos de peças e comprovantes relacionados a ordens de serviço. O exemplo é ilustrativo. A oficina quer associar os arquivos ao atendimento sem depender de o funcionário deixar uma conversa aberta no computador.

O sistema recebe o evento, identifica a organização e registra a mensagem uma única vez. Um trabalhador consulta a mídia, baixa o arquivo e coloca o conteúdo em quarentena. Só depois de aprovado ele fica disponível na ordem correta. Se ainda não houver ordem associada, a equipe resolve a vinculação em uma tela de pendências.

Uma foto pode ser suficiente para preparar o orçamento, mas não para confirmar o estado real de uma peça. A interface mostra essa limitação e evita que uma classificação por IA vire autorização automática de reparo. Um comprovante recebido também não deve alterar sozinho o estado financeiro do pedido.

Se o cliente reenviar a mesma mensagem por causa de uma falha aparente, o sistema mantém o histórico sem duplicar trabalho desnecessariamente. Se enviar outra foto, ela ganha identidade própria. A deduplicação técnica não deve apagar evidências diferentes só porque os nomes de arquivo coincidem.

Na entrega do piloto, a oficina testa transferência interrompida, token inválido, arquivo bloqueado, evento repetido e tentativa de abrir um anexo de outro cliente. O responsável confirma na tela o estado de cada caso. O teste só termina quando também consegue excluir um arquivo e verificar o tratamento das cópias derivadas.

Retenção: definir quando cada cópia deixa de existir

A validade de cinco minutos não define o prazo da sua cópia. Também não é um prazo legal de guarda. Defina a finalidade de cada classe de documento e faça a pessoa responsável pela política de dados aprovar os critérios. O guia de LGPD e segurança na implantação de IA contextualiza esse trabalho na operação brasileira.

Registre a data prevista de exclusão no próprio objeto ou em seu cadastro. Especifique quando o relógio começa: recebimento, encerramento do atendimento ou outro marco aprovado. Defina exceções documentadas e responsáveis por revisá-las. Não permita que qualquer usuário transforme “guardar por precaução” em retenção ilimitada.

Inclua miniaturas, versões convertidas, OCR, transcrições, exportações e dados enviados a fornecedores. Um documento apagado da tela pode continuar em uma pasta temporária ou em um índice de pesquisa. Faça uma lista dos destinos percorridos pelo conteúdo e implemente a exclusão em cada um, respeitando o ciclo dos backups.

A operação oficial de exclusão de mídia usa o identificador no provedor. Ela deve ser tratada separadamente da limpeza do armazenamento interno. Apagar de um lado não comprova que o outro foi limpo. Mantenha evidências operacionais da execução sem conservar o conteúdo que deveria ser eliminado.

Não dependa de um prazo presumido de disponibilidade do identificador para adiar o download. A mídia deve ser recuperada no fluxo normal e uma falha precisa aparecer para a equipe. Quando o conteúdo não puder mais ser obtido, ofereça um caminho claro para solicitar novo envio, sem simular que o anexo está arquivado.

Erros comuns

• Salvar apenas a URL no CRM. A visualização pode funcionar no teste e falhar depois. Salve uma cópia autorizada quando houver finalidade para isso.
• Expor token ao atendente. O navegador deve acessar uma rota interna autorizada, sem receber a credencial da Meta.
• Executar tudo dentro do webhook. Downloads lentos e análises podem comprometer o recebimento. Use fila durável e estados observáveis.
• Tratar repetição como novo trabalho. Aplique chave única e proteja transições contra concorrência.
• Guardar derivados sem prazo. OCR e transcrição também precisam entrar na política de retenção.
• Confundir exclusão local com exclusão no provedor. Registre cada operação e trate falhas separadamente.

Perguntas frequentes

Posso enviar a URL temporária para o navegador?

Evite construir a experiência com essa dependência. Faça a recuperação no servidor e exponha uma rota interna com autorização, ou um mecanismo temporário do seu armazenamento. Isso permite controlar acesso e não entregar a credencial da API ao usuário.

O arquivo some da minha cópia quando a URL expira?

Não. A expiração restringe aquele endereço de download. A cópia que sua aplicação já salvou tem ciclo próprio e continuará existindo até a exclusão conforme sua configuração. Por isso, a política de retenção precisa ser implementada explicitamente.

Devo repetir qualquer erro de download?

Não. Classifique falhas transitórias, problemas de autenticação e conteúdo indisponível. Limite as tentativas e encaminhe casos que exigem correção humana. Antes de tentar novamente após espera, recupere uma URL atualizada.

Preciso usar IA para receber anexos?

Não. Recebimento, armazenamento e controle de acesso são responsabilidades do sistema. Acrescente OCR, transcrição ou classificação apenas quando houver uma necessidade definida e um critério para avaliar a qualidade do resultado.

Fontes e leitura recomendada

• Meta: coleção oficial de operações de mídia
• Meta: recuperação e validade da URL de mídia
• Meta: exclusão de mídia pelo identificador
• Meta: configuração de webhooks da Graph API
• WhatsApp for Business: exemplo oficial de operações de mídia

Para situar o canal no conjunto de produtos da empresa, consulte também a página de integrações da Meta. A integração de mídia descrita aqui deve ser avaliada como parte do fluxo de atendimento e da gestão de dados.