{"id":516,"date":"2026-10-28T16:05:44","date_gmt":"2026-10-28T16:05:44","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/baixar-midia-webhook-whatsapp\/"},"modified":"2026-10-28T16:05:53","modified_gmt":"2026-10-28T16:05:53","slug":"baixar-midia-webhook-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/baixar-midia-webhook-whatsapp\/","title":{"rendered":"Como receber e baixar a m\u00eddia que o cliente envia pela API do WhatsApp"},"content":{"rendered":"\n

Atualizado em 28\/10\/2026<\/em><\/p>\n\n\n\n

Quando o cliente manda uma foto, um PDF, um \u00e1udio ou um v\u00eddeo, o webhook da API do WhatsApp n\u00e3o traz o arquivo: traz um media id<\/strong>. Para baixar, voc\u00ea faz GET \/{media-id}<\/code> para obter uma URL tempor\u00e1ria, que expira em 5 minutos<\/strong>, e depois faz um GET<\/code> nessa URL com o seu token de acesso no cabe\u00e7alho Authorization<\/code>. Como o media id recebido por webhook vale s\u00f3 7 dias<\/strong>, o certo \u00e9 baixar logo e guardar o arquivo no seu pr\u00f3prio storage.<\/p>\n\n\n\n

Este guia mostra o fluxo completo, os campos de cada tipo de m\u00eddia, os limites de tamanho, como conferir a integridade do arquivo e exemplos em cURL, Node.js e Python, incluindo o envio para o Amazon S3.<\/p>\n\n\n\n

O fluxo em 4 passos<\/h2>\n\n\n\n
    \n
  1. Webhook<\/strong>: chega uma mensagem com type<\/code> igual a image<\/code>, document<\/code>, audio<\/code>, video<\/code> ou sticker<\/code>, com o id<\/code> da m\u00eddia.<\/li>\n\n\n
  2. URL tempor\u00e1ria<\/strong>: GET https:\/\/graph.facebook.com\/v26.0\/{media-id}<\/code> devolve url<\/code>, mime_type<\/code>, sha256<\/code> e file_size<\/code>.<\/li>\n\n\n
  3. Download<\/strong>: GET<\/code> na url<\/code> com Authorization: Bearer <token><\/code>. Sem o token, a requisi\u00e7\u00e3o falha.<\/li>\n\n\n
  4. Armazenamento<\/strong>: salve no seu storage (S3, GCS, disco) e grave no banco o caminho do arquivo, nunca a URL da Meta.<\/li>\n\n<\/ol>\n\n\n\n

    Os prazos v\u00eam da documenta\u00e7\u00e3o de m\u00eddia da Meta<\/a>: URLs de m\u00eddia expiram em 5 minutos (depois disso, basta consultar o media id de novo para gerar outra), media ids vindos de webhooks expiram em 7 dias e media ids gerados por upload expiram em 30 dias.<\/p>\n\n\n\n

    O que chega no webhook<\/h2>\n\n\n\n

    Este \u00e9 o formato de uma imagem recebida, segundo a refer\u00eancia de webhooks de imagem<\/a> (valores de exemplo):<\/p>\n\n\n\n

    {\n  \"object\": \"whatsapp_business_account\",\n  \"entry\": [{\n    \"id\": \"WABA_ID\",\n    \"changes\": [{\n      \"field\": \"messages\",\n      \"value\": {\n        \"messaging_product\": \"whatsapp\",\n        \"metadata\": {\n          \"display_phone_number\": \"5511999999999\",\n          \"phone_number_id\": \"PHONE_NUMBER_ID\"\n        },\n        \"contacts\": [{ \"profile\": { \"name\": \"Maria\" }, \"wa_id\": \"5511988887777\" }],\n        \"messages\": [{\n          \"from\": \"5511988887777\",\n          \"id\": \"wamid.HBgLNTUx...\",\n          \"timestamp\": \"1761650000\",\n          \"type\": \"image\",\n          \"image\": {\n            \"caption\": \"Comprovante\",\n            \"mime_type\": \"image\/jpeg\",\n            \"sha256\": \"SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI=\",\n            \"id\": \"1003383421387256\",\n            \"url\": \"https:\/\/lookaside.fbsbx.com\/whatsapp_business\/attachments\/?mid=...\"\n          }\n        }]\n      }\n    }]\n  }]\n}<\/code><\/pre>\n\n\n\n
    O objeto muda de nome conforme o tipo (image<\/code>, document<\/code>, audio<\/code>, video<\/code>, sticker<\/code>), mas a estrutura \u00e9 parecida. Documentos trazem tamb\u00e9m filename<\/code>, \u00fatil para salvar com o nome original.<\/p>\n\n\n\n
    Repare no campo url<\/code>. A Meta come\u00e7ou a liberar esse campo no pr\u00f3prio webhook de forma gradual a partir de 12\/11\/2025, permitindo pular o passo 2 e baixar direto com o token. Como a libera\u00e7\u00e3o \u00e9 gradual, seu c\u00f3digo deve funcionar com e sem ele: use a url<\/code> se vier e, se n\u00e3o vier ou o download der erro, consulte o media id.<\/p>\n\n\n\n
    Campo<\/th>Para que serve<\/th><\/tr><\/thead>
    id<\/code><\/td>Media id; use para gerar a URL de download<\/td><\/tr>
    mime_type<\/code><\/td>Tipo do arquivo (image\/jpeg<\/code>, application\/pdf<\/code>, audio\/ogg<\/code>…)<\/td><\/tr>
    sha256<\/code><\/td>Hash do arquivo, para conferir integridade<\/td><\/tr>
    caption<\/code><\/td>Legenda enviada pelo cliente, quando houver<\/td><\/tr>
    filename<\/code><\/td>Nome original (documentos)<\/td><\/tr>
    url<\/code><\/td>URL de download direto, em libera\u00e7\u00e3o gradual<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Tipos e limites de tamanho<\/h2>\n\n\n\n
    A tabela abaixo resume os tipos suportados e os tamanhos m\u00e1ximos da p\u00e1gina de m\u00eddia da Meta. Ela ajuda a dimensionar o storage e o tempo limite do download:<\/p>\n\n\n\n
    Tipo<\/th>Formatos<\/th>Tamanho m\u00e1ximo<\/th><\/tr><\/thead>
    \u00c1udio<\/td>AAC, AMR, MP3, M4A, OGG (s\u00f3 codec OPUS, mono)<\/td>16 MB<\/td><\/tr>
    Documento<\/td>TXT, XLS, XLSX, DOC, DOCX, PPT, PPTX, PDF<\/td>100 MB<\/td><\/tr>
    Imagem<\/td>JPEG, PNG (8 bits, RGB ou RGBA)<\/td>5 MB<\/td><\/tr>
    Figurinha<\/td>WebP<\/td>500 KB animada, 100 KB est\u00e1tica<\/td><\/tr>
    V\u00eddeo<\/td>3GP, MP4 (H.264 e AAC)<\/td>16 MB<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Notas de voz chegam como mensagens do tipo audio<\/code>. Se voc\u00ea vai passar o \u00e1udio para um servi\u00e7o de transcri\u00e7\u00e3o, confira o mime_type<\/code> recebido e se o servi\u00e7o aceita aquele formato; se n\u00e3o aceitar, converta antes.<\/p>\n\n\n\n
    Exemplo com cURL<\/h2>\n\n\n\n
    Passo 2, obter a URL:<\/p>\n\n\n\n
    curl \"https:\/\/graph.facebook.com\/v26.0\/1003383421387256\" \\\n  -H \"Authorization: Bearer $TOKEN\"<\/code><\/pre>\n\n\n\n
    Resposta:<\/p>\n\n\n\n
    {\n  \"messaging_product\": \"whatsapp\",\n  \"url\": \"https:\/\/lookaside.fbsbx.com\/whatsapp_business\/attachments\/?mid=...\",\n  \"mime_type\": \"image\/jpeg\",\n  \"sha256\": \"SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI=\",\n  \"file_size\": 303833,\n  \"id\": \"1003383421387256\"\n}<\/code><\/pre>\n\n\n\n
    Passo 3, baixar:<\/p>\n\n\n\n
    curl -L \"URL_RETORNADA\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -o comprovante.jpg<\/code><\/pre>\n\n\n\n
    Opcionalmente, envie phone_number_id<\/code> como par\u00e2metro de consulta no passo 2: assim a Meta s\u00f3 processa a requisi\u00e7\u00e3o se a m\u00eddia pertencer \u00e0quele n\u00famero, uma prote\u00e7\u00e3o \u00fatil quando a mesma aplica\u00e7\u00e3o atende v\u00e1rios n\u00fameros.<\/p>\n\n\n\n
    Exemplo em Node.js<\/h2>\n\n\n\n
    import crypto from 'node:crypto';\nimport { S3Client, PutObjectCommand } from '@aws-sdk\/client-s3';\n\nconst GRAPH = 'https:\/\/graph.facebook.com\/v26.0';\nconst TOKEN = process.env.WHATSAPP_TOKEN;\nconst s3 = new S3Client({ region: process.env.AWS_REGION });\n\nasync function obterUrl(mediaId) {\n  const res = await fetch(`${GRAPH}\/${mediaId}`, {\n    headers: { Authorization: `Bearer ${TOKEN}` },\n  });\n  if (!res.ok) throw new Error(`media ${mediaId}: HTTP ${res.status}`);\n  return res.json(); \/\/ { url, mime_type, sha256, file_size, id }\n}\n\nasync function baixar(url) {\n  const res = await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } });\n  if (!res.ok) throw Object.assign(new Error('download falhou'), { status: res.status });\n  return Buffer.from(await res.arrayBuffer());\n}\n\nexport async function salvarMidia(midia, chave) {\n  let info = { url: midia.url, sha256: midia.sha256, mime_type: midia.mime_type };\n  let arquivo;\n  try {\n    if (!info.url) throw new Error('sem url no webhook');\n    arquivo = await baixar(info.url);\n  } catch {\n    info = await obterUrl(midia.id); \/\/ gera uma URL nova\n    arquivo = await baixar(info.url);\n  }\n\n  const hash = crypto.createHash('sha256').update(arquivo).digest('base64');\n  if (info.sha256 && hash !== info.sha256) throw new Error('hash n\u00e3o confere');\n\n  await s3.send(new PutObjectCommand({\n    Bucket: process.env.BUCKET,\n    Key: chave,\n    Body: arquivo,\n    ContentType: info.mime_type,\n  }));\n  return chave;\n}<\/code><\/pre>\n\n\n\n
    O hash sha256<\/code> dos exemplos da Meta est\u00e1 em base64, por isso a compara\u00e7\u00e3o usa digest('base64')<\/code>. Se no seu caso o formato vier diferente, registre os dois valores antes de ativar a checagem.<\/p>\n\n\n\n
    Exemplo em Python<\/h2>\n\n\n\n
    import base64\nimport hashlib\nimport os\n\nimport boto3\nimport httpx\n\nGRAPH = \"https:\/\/graph.facebook.com\/v26.0\"\nTOKEN = os.environ[\"WHATSAPP_TOKEN\"]\nHEADERS = {\"Authorization\": f\"Bearer {TOKEN}\"}\ns3 = boto3.client(\"s3\")\n\n\ndef obter_url(client: httpx.Client, media_id: str) -> dict:\n    r = client.get(f\"{GRAPH}\/{media_id}\", headers=HEADERS)\n    r.raise_for_status()\n    return r.json()\n\n\ndef salvar_midia(midia: dict, chave: str) -> str:\n    with httpx.Client(timeout=60, follow_redirects=True) as client:\n        info = obter_url(client, midia[\"id\"])\n        r = client.get(info[\"url\"], headers=HEADERS)\n        if r.status_code == 404:  # URL vencida: gere outra e tente de novo\n            info = obter_url(client, midia[\"id\"])\n            r = client.get(info[\"url\"], headers=HEADERS)\n        r.raise_for_status()\n\n    calculado = base64.b64encode(hashlib.sha256(r.content).digest()).decode()\n    if info.get(\"sha256\") and calculado != info[\"sha256\"]:\n        raise ValueError(\"hash n\u00e3o confere\")\n\n    s3.put_object(\n        Bucket=os.environ[\"BUCKET\"],\n        Key=chave,\n        Body=r.content,\n        ContentType=info[\"mime_type\"],\n    )\n    return chave<\/code><\/pre>\n\n\n\n
    Para documentos de at\u00e9 100 MB, carregar tudo em mem\u00f3ria pode pesar. Nesse caso, baixe em stream<\/em> para um arquivo tempor\u00e1rio e use upload_fileobj<\/code> do boto3 ou o Upload<\/code> do pacote @aws-sdk\/lib-storage<\/code> no Node, que fazem upload em partes.<\/p>\n\n\n\n
    Onde colocar isso na arquitetura<\/h2>\n\n\n\n
    N\u00e3o baixe a m\u00eddia dentro da requisi\u00e7\u00e3o do webhook. O endpoint deve validar a assinatura, enfileirar o evento e responder 200<\/code> r\u00e1pido; um worker separado faz o download e o upload. Assim, um v\u00eddeo grande n\u00e3o segura o webhook nem gera reenvios da Meta. Sobre a valida\u00e7\u00e3o, veja como validar a assinatura do webhook<\/a>.<\/p>\n\n\n\n
    Algumas boas pr\u00e1ticas:<\/p>\n\n\n\n