Mídia na API do WhatsApp: formatos aceitos e limites de tamanho

Devo fazer upload da mídia ou enviar um link?

A Meta recomenda fazer o upload do arquivo e enviar o media ID. Também é possível enviar um link para um arquivo em um servidor público, mas as referências da Meta para imagem, vídeo e documento dizem para preferir o ID de upload por melhor desempenho, e a orientação sobre throughput diz o mesmo para volumes maiores.

Com o endpoint da própria Meta, um upload é um POST para /<PHONE_NUMBER_ID>/media com o arquivo, seu tipo MIME e messaging_product=whatsapp, e a resposta é {"id": "<MEDIA_ID>"}. Os arquivos enviados são criptografados e mantidos por 30 dias, a menos que você os exclua antes.

No endpoint de WhatsApp da OmniChannels.ai, uma mensagem de mídia aceita mediaUrl (uma URL HTTPS pública) ou mediaFile (um arquivo enviado junto com a requisição), com a legenda em content. Veja a documentação da API do WhatsApp. Pergunte à nossa equipe como a sua conta trata o armazenamento e a reutilização de mídia em envios grandes.

Por quanto tempo os media IDs continuam válidos?

A Meta documenta 30 dias para um ID retornado por um upload e 7 dias para um ID recebido em um webhook de mensagem recebida. A URL de download retornada para um ID expira em 5 minutos.

Consequências práticas:

• Não guarde um media ID em cache por meses. Armazene o arquivo original e faça novo upload quando um ID for rejeitado.
• Baixe os arquivos recebidos assim que o evento chegar e mantenha a sua própria cópia.
• Nunca armazene uma URL de download obtida; peça uma nova quando precisar.

Posso adicionar legendas às mensagens de mídia?

Sim. As mensagens de imagem, vídeo e documento aceitam uma legenda opcional de até 1.024 caracteres, segundo as referências de mensagens da Meta. As legendas são texto simples ao lado do arquivo.

As mensagens de áudio e de figurinha não têm legenda nesse modelo. Se precisar de palavras junto com um áudio, envie uma mensagem de texto curta ao lado. Dentro da janela de atendimento ao cliente, as legendas são livres; fora dela, a mídia precisa ir dentro de um template aprovado.

Como a mídia funciona em templates de mensagem?

Um template pode ter uma imagem, um vídeo ou um documento no cabeçalho, e esse cabeçalho é fixado quando você cria o template. Ao enviar um template para aprovação, você fornece um arquivo de exemplo e pode informar o arquivo real no momento do envio.

Na nossa API, headerFormat pode ser IMAGE, VIDEO ou DOCUMENT na criação, headerFile leva o exemplo e mediaUrl no momento do envio substitui a mídia do cabeçalho. Consulte a documentação de templates da Meta para os requisitos do arquivo de exemplo. Veja categorias e aprovação de templates e exemplos de templates.

Como baixo a mídia que um cliente envia?

A mídia recebida chega em um webhook com um media ID; você a converte em uma URL e a baixa com autorização.

1. Leia o media ID no evento da mensagem recebida.
2. Solicite a URL da mídia para esse ID. A resposta da Meta inclui url, mime_type, sha256 e file_size.
3. Faça um GET nessa URL com o cabeçalho Authorization: Bearer <token>. Sem o token, a requisição falha.
4. Verifique o cabeçalho Content-Type e o valor de sha256 e depois armazene o arquivo.
5. Em caso de 404, solicite uma nova URL e tente de novo; se ainda falhar, renove o token de acesso.

O tamanho máximo de mídia recebida da Meta na Cloud API é de 100 MB. Um arquivo maior aciona um webhook com o código de erro 131052; peça ao cliente que envie um arquivo menor ou o compartilhe de outra forma. Faça uma verificação de segurança em todo arquivo antes de abri-lo internamente. Veja o guia de webhooks e confirme com o seu engenheiro de onboarding como a mídia recebida é entregue na sua conta.

Exemplo prático: uma clínica odontológica que envia laudos

A "Nile Smile Clinic" (sintética), no Cairo, envia cartões de consulta e laudos de radiografia.

1. Os cartões de consulta são imagens PNG de 300 KB com uma legenda de duas linhas. Bem abaixo de 5 MB.
2. Os laudos de tratamento são PDFs de 2 a 8 MB, chamados report-2026-0381.pdf, enviados como documentos.
3. Um vídeo de 25 MB com um tour pela clínica é grande demais para vídeo. A equipe o recodifica como MP4 H.264/AAC com menos de 16 MB e com faststart.
4. Os pacientes enviam fotos de receitas. A caixa de entrada baixa cada arquivo imediatamente, porque o ID recebido expira em 7 dias.
5. Uma saudação em voz é exportada como OGG Opus mono, já que as outras variantes de OGG são rejeitadas.

Quais são os erros mais comuns?

• Julgar só pelo tamanho. Uma imagem de 3 MB com formato de cor errado ou um vídeo com codec errado ainda falha.
• MIME incompatível. Um .jpg servido como application/octet-stream é uma causa clássica do erro 131053.
• Usar um link lento ou privado, como um link assinado que expirou ou uma página protegida por login.
• Confiar em um media ID antigo. Os IDs expiram em 30 dias.
• Ignorar a expiração dos IDs recebidos. Os arquivos dos clientes devem ser salvos em até 7 dias.
• WebP animado como imagem. É rejeitado; use uma figurinha ou um vídeo.
• Os limites mudam. Reconfira a referência da Meta antes de fixar regras de validação no código.

Como a OmniChannels.ai ajuda

A OmniChannels.ai envia mensagens de imagem, vídeo, áudio, documento e figurinha do WhatsApp por uma única API, com link público ou arquivo enviado e legenda, e exibe mídia e anexos na caixa de entrada compartilhada. A BroadNet é uma Meta Business Solution Provider oficial, então templates com cabeçalho de imagem, vídeo ou documento podem ser criados e acompanhados com o status de aprovação. Leia a documentação da API do WhatsApp e os erros e limites, ou conheça o canal WhatsApp.