Como receber mídia na API oficial do WhatsApp sem lidar com criptografia

Resposta curta: quando o cliente manda uma foto, um áudio, um vídeo ou um documento, o webhook não traz o arquivo. Ele traz o tipo, um código de verificação, um identificador de mídia e uma URL que não abre: colar essa URL no navegador devolve erro de autenticação, porque a mídia sai criptografada da Meta. Pela Datafy API você resolve isso com uma chamada: GET https://cloud.datafyapi.com.br/media/{id}, passando o identificador que veio no webhook, devolve uma URL pronta para usar, válida por 30 dias. Como resume Israel Henrique, CTO da Datafy: "ela vem criptografada e você precisa descriptografar. Aqui a gente já fez esse trabalho para você."

Principais pontos

• O webhook traz identificador, não arquivo. No objeto da mídia vêm o mime_type, o sha256 e o id, além de uma URL que só serve para chamada autenticada.
• A URL do payload não abre no navegador. O erro é de autenticação, e ele aparece em todos os tipos de mídia, não só em imagem.
• A rota simplificada faz o trabalho pesado. GET /media/{id} recebe o identificador do webhook e devolve uma URL hospedada em files.datafyapi.com.br, válida por 30 dias.
• Peça a URL quando a mensagem chega. O identificador de mídia que vem no webhook expira em 7 dias, segundo a documentação da Meta. Não deixe para depois.
• Precisa guardar por mais tempo? Baixe o arquivo pela URL da Datafy dentro dos 30 dias e salve no seu próprio armazenamento.

Antes de começar

Receber mídia depende de duas coisas já prontas: o número conectado e o webhook ativo. A mídia só aparece para quem está ouvindo o evento de mensagens.

O token nasce na criação do canal, antes da conexão do número. Se você ainda não sabe quais são os seus identificadores, comece por aqui:

GET https://cloud.datafyapi.com.br/me
Authorization: Bearer sk_live_xxx

{
  "cliente_id": "uuid-do-cliente",
  "phone_number_id": "106540352242922",
  "waba_id": "366634483210360",
  "business_id": "123456789"
}

Quem só tem o token descobre por essa chamada o phone_number_id, o waba_id e o business_id. É o primeiro passo de qualquer integração, e vale a pena guardar os três em variável de ambiente.

Passo 1: ver a mídia chegar

No painel, abra o número conectado e vá até a aba de webhooks. Cada URL cadastrada tem a sua lista de execuções, que é onde o payload cru aparece, um por entrega.

Tire uma foto com o celular e mande para o número conectado. A mensagem chega no aplicativo como qualquer outra, e a entrega aparece na lista de execuções em seguida.

Abra a execução. No corpo, dentro de messages, você encontra o campo type com o valor image e, ao lado, um objeto image.

Passo 2: o que vem no payload

O objeto da mídia tem sempre a mesma estrutura, mudando só o nome conforme o tipo:

{
  "messages": [
    {
      "from": "5511999999999",
      "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDN...",
      "timestamp": "1759100000",
      "type": "image",
      "image": {
        "mime_type": "image/jpeg",
        "sha256": "f20c6c7c34d56b9e2b0a1f7c5d8e9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
        "id": "1037543291543636"
      }
    }
  ]
}

Três campos importam:

• mime_type diz o formato do arquivo, e é por ele que você decide a extensão ao salvar.
• sha256 é o código de verificação do conteúdo. Serve para conferir integridade se você guardar o arquivo.
• id é o identificador da mídia, e é o único campo que você precisa copiar.

O payload pode trazer também uma URL de download. Ela não abre. Clicar nela no navegador devolve erro de autenticação, porque o acesso é autenticado e a mídia está criptografada. É esse ponto que faz muita integração parar no primeiro dia.

Passo 3: copiar o identificador e pedir a URL

Copie o valor de image.id e chame a rota de mídia. Na documentação, ela aparece na seção Mídia, na operação de obter a URL da mídia:

GET https://cloud.datafyapi.com.br/media/1037543291543636
Authorization: Bearer sk_live_xxx

{
  "url": "https://files.datafyapi.com.br/uuid-cliente/2026/09/1759100000000-a1b2c3d4.jpg",
  "mime_type": "image/jpeg",
  "size": 86620
}

Abra a URL devolvida e a imagem aparece, sem token, sem descriptografia e sem etapa intermediária. O {id} é sempre o identificador que veio no webhook: image.id, audio.id, video.id, document.id ou sticker.id.

Resposta 404 significa identificador inválido ou mídia expirada. É o sinal de que o prazo de 7 dias do identificador da Meta passou.

Como receber mídias na API oficial do WhatsAppCanal DATA7 · 4 min · assistir no YouTube

Passo 4: o mesmo caminho com áudio

Grave um áudio no celular e mande para o número. No payload, type vira audio e o objeto audio traz um campo a mais:

{
  "type": "audio",
  "audio": {
    "mime_type": "audio/ogg; codecs=opus",
    "sha256": "a1b2c3d4e5f6...",
    "id": "2048651937482910",
    "voice": true
  }
}

O campo voice com valor true indica que aquilo foi gravado como mensagem de voz no aplicativo, e não anexado como arquivo de áudio. O caminho para pegar o arquivo é idêntico: copia o id, chama GET /media/{id}, recebe a URL.

Vale guardar esse detalhe, porque ele também existe no envio: para mandar um áudio que chega como bolha de voz, você precisa marcar voice e usar o formato certo. Como enviar está aqui.

Quando chega cada tipo, e o que você recebe

A última linha é a que pega quem está fazendo coexistência: no histórico importado, a mídia não vem dentro da conversa. Como a sincronização funciona está aqui.

Os prazos, sem confundir

São quatro prazos diferentes, e misturá-los é a causa mais comum de arquivo perdido:

Atenção a uma correção importante. O prazo de 30 dias vale para a URL da Datafy e para a mídia que você mesmo sobe. O identificador que chega no webhook expira em 7 dias, e isso está escrito na documentação de mídia da Meta. Se você processa mídia em lote, uma vez por semana, vai encontrar 404 em parte dos identificadores. O caminho seguro é pedir a URL no momento em que a mensagem chega.

O caminho espelhado, quando você quer o binário

A rota simplificada resolve a maioria dos casos. Mas se você quer o arquivo direto do armazenamento da Meta, o espelho da Cloud API está disponível, e são duas chamadas.

Primeiro, a consulta do identificador:

GET https://cloud.datafyapi.com.br/v1/1037543291543636?phone_number_id=106540352242922
Authorization: Bearer sk_live_xxx

{
  "messaging_product": "whatsapp",
  "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=1037543291543636",
  "mime_type": "image/jpeg",
  "sha256": "f20c6c7c34d56b...",
  "file_size": 23418,
  "id": "1037543291543636"
}

Depois, o download, com o token no cabeçalho:

GET https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=1037543291543636
Authorization: Bearer sk_live_xxx

Três cuidados que a documentação da Datafy destaca nesse caminho:

A URL vale 5 minutos. Baixe imediatamente depois de consultar. Se voltar 404, consulte de novo e baixe outra vez.

O token é obrigatório no download. Clicar no navegador dá erro, e é justamente o comportamento que a rota simplificada elimina.

O parâmetro phone_number_id é opcional e útil. Ele valida que aquela mídia pertence ao seu número antes de a URL ser devolvida.

Existe ainda DELETE /v1/{media_id}, que apaga a mídia do armazenamento da Meta. Faz sentido para quem sobe arquivo para enviar e quer limpar depois, não para mídia recebida.

Marcar como lida no fim do processamento

Quem monta atendimento costuma querer os dois tiques azuis só depois de o arquivo estar salvo. A rota simplificada dispensa o identificador do número:

POST https://cloud.datafyapi.com.br/messages/read
Authorization: Bearer sk_live_xxx
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDN..."
}

Só mensagem recebida pode ser marcada como lida, e a documentação recomenda fazer isso em até 30 dias. Use o id da mensagem, não o da mídia.

Formatos e tamanhos que podem chegar

Os limites são da Meta, valem na entrada e na saída, e é bom conhecê-los antes de dimensionar armazenamento:

Um documento de 100 MB por conversa muda a conta do seu armazenamento bem mais rápido do que a imagem de 5 MB. Se o seu produto guarda tudo, essa tabela é o seu pior caso.

O que muda com a Datafy

Não muda: formato, tamanho, prazo do identificador e criptografia são regra da Meta. Nenhuma plataforma altera isso.

Muda a descriptografia. A mídia sai cifrada da Meta, e a plataforma entrega a URL pronta numa chamada só. Essa é a parte que você deixa de escrever.

Muda a validade útil. A URL de download da Meta vive 5 minutos. A URL da Datafy vive 30 dias, hospedada em files.datafyapi.com.br, o que dá tempo de o seu sistema processar em fila sem correr contra o relógio.

Muda a quantidade de chamadas. Uma, em vez de consultar o identificador e baixar o binário em seguida.

O que continua com você: guardar o arquivo além dos 30 dias, se o seu caso exige, e tratar o 404 como parte normal do fluxo.

Perguntas frequentes

Por que a URL que vem no webhook dá erro de autenticação?

Porque a mídia da API oficial é entregue criptografada e o acesso é autenticado. Aquela URL não foi feita para abrir no navegador. O caminho é usar o identificador para pedir uma URL de uso.

Quanto tempo vale a URL devolvida por GET /media/{id}?

30 dias, hospedada em files.datafyapi.com.br. Depois disso o arquivo não está mais lá.

E se eu precisar do arquivo por mais tempo que isso?

Baixe pela URL da Datafy dentro do prazo e salve no seu armazenamento. É o caminho que o próprio CTO recomenda: se quiser mais dias, baixe e guarde no seu storage.

O identificador de mídia expira?

Sim. O identificador que chega no webhook expira em 7 dias, segundo a documentação de mídia da Meta. Esse prazo é diferente dos 30 dias da mídia que você sobe para enviar.

Recebi 404 na chamada. O que aconteceu?

Ou o identificador está errado, ou a mídia já expirou. Confira se você copiou o id de dentro do objeto da mídia, e não o id da mensagem, que começa com wamid.

Consigo ver a imagem no log de mensagens do painel?

Não. O log ao vivo mostra o payload e sinaliza que chegou uma mídia, mas não exibe o arquivo. Para o conteúdo, a chamada de mídia é obrigatória. Como usar o log está aqui.

Recebi mídia num histórico importado e o objeto vem vazio. É erro?

Não. No histórico da coexistência a mídia aparece como media_placeholder, sem conteúdo, e o arquivo chega em webhooks separados, casados pelo wamid. Só as mídias mais recentes têm arquivo disponível.

Como decidir

Se o seu sistema só precisa mostrar a mídia na tela de atendimento, use GET /media/{id} no momento em que a mensagem chega e guarde a URL devolvida. Ela vale 30 dias e é pública, então não há token para proteger no front-end.

Se o seu produto precisa do arquivo depois disso, ou se você tem obrigação de retenção, faça o download pela mesma URL e salve no seu armazenamento no mesmo processamento. Nunca deixe a resolução da mídia para um job semanal: o identificador da Meta expira em 7 dias e você perde o arquivo.

E se você está migrando de código que falava direto com a Meta, mantenha o caminho de duas chamadas só onde precisa do binário. No resto, a rota simplificada apaga duas etapas do seu código. O que muda entre os dois caminhos está aqui.

Leia também

• Como enviar imagem, documento e áudio pela API oficial
• Como ver o payload das mensagens em tempo real
• Como a Datafy API funciona: um espelho da Cloud API
• Como criar um atendimento no WhatsApp do zero