{"id":518,"date":"2026-10-28T16:05:49","date_gmt":"2026-10-28T16:05:49","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/descargar-multimedia-webhook-whatsapp\/"},"modified":"2026-10-28T16:06:08","modified_gmt":"2026-10-28T16:06:08","slug":"descargar-multimedia-webhook-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/es\/descargar-multimedia-webhook-whatsapp\/","title":{"rendered":"C\u00f3mo recibir y descargar los archivos que el cliente env\u00eda por la API de WhatsApp"},"content":{"rendered":"\n

Actualizado el 28\/10\/2026<\/em><\/p>\n\n\n\n

Cuando el cliente env\u00eda una foto, un PDF, un audio o un video, el webhook de la API de WhatsApp no trae el archivo: trae un media id<\/strong>. Para descargarlo, haces GET \/{media-id}<\/code> para obtener una URL temporal, que expira en 5 minutos<\/strong>, y luego un GET<\/code> a esa URL con tu token de acceso en el encabezado Authorization<\/code>. Como el media id recibido por webhook vale solo 7 d\u00edas<\/strong>, lo correcto es descargarlo enseguida y guardar el archivo en tu propio almacenamiento.<\/p>\n\n\n\n

Esta gu\u00eda muestra el flujo completo, los campos de cada tipo de archivo, los l\u00edmites de tama\u00f1o, c\u00f3mo verificar la integridad y ejemplos en cURL, Node.js y Python, incluido el env\u00edo a Amazon S3.<\/p>\n\n\n\n

El flujo en 4 pasos<\/h2>\n\n\n\n
    \n
  1. Webhook<\/strong>: llega un mensaje con type<\/code> igual a image<\/code>, document<\/code>, audio<\/code>, video<\/code> o sticker<\/code>, con el id<\/code> del archivo.<\/li>\n\n\n
  2. URL temporal<\/strong>: GET https:\/\/graph.facebook.com\/v26.0\/{media-id}<\/code> devuelve url<\/code>, mime_type<\/code>, sha256<\/code> y file_size<\/code>.<\/li>\n\n\n
  3. Descarga<\/strong>: GET<\/code> a la url<\/code> con Authorization: Bearer <token><\/code>. Sin el token, la solicitud falla.<\/li>\n\n\n
  4. Almacenamiento<\/strong>: guarda el archivo en tu storage (S3, GCS, disco) y registra en la base de datos su ruta, nunca la URL de Meta.<\/li>\n\n<\/ol>\n\n\n\n

    Los plazos vienen de la documentaci\u00f3n de multimedia de Meta<\/a>: las URL expiran en 5 minutos (despu\u00e9s basta con consultar el media id otra vez para generar una nueva), los media id que llegan por webhook expiran en 7 d\u00edas y los generados por carga (upload) expiran en 30 d\u00edas.<\/p>\n\n\n\n

    Qu\u00e9 llega en el webhook<\/h2>\n\n\n\n

    Este es el formato de una imagen recibida, seg\u00fan la referencia del webhook de im\u00e1genes<\/a> (valores de ejemplo):<\/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\": \"5215512345678\",\n          \"phone_number_id\": \"PHONE_NUMBER_ID\"\n        },\n        \"contacts\": [{ \"profile\": { \"name\": \"Mar\u00eda\" }, \"wa_id\": \"5215598765432\" }],\n        \"messages\": [{\n          \"from\": \"5215598765432\",\n          \"id\": \"wamid.HBgNNTIx...\",\n          \"timestamp\": \"1761650000\",\n          \"type\": \"image\",\n          \"image\": {\n            \"caption\": \"Comprobante\",\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
    El objeto cambia de nombre seg\u00fan el tipo (image<\/code>, document<\/code>, audio<\/code>, video<\/code>, sticker<\/code>), pero la estructura es parecida. Los documentos tambi\u00e9n traen filename<\/code>, \u00fatil para guardar con el nombre original.<\/p>\n\n\n\n
    F\u00edjate en el campo url<\/code>. Meta empez\u00f3 a habilitarlo en el propio webhook de forma gradual desde el 12\/11\/2025, lo que permite saltar el paso 2 y descargar directamente con el token. Como la habilitaci\u00f3n es gradual, tu c\u00f3digo debe funcionar con y sin \u00e9l: usa la url<\/code> si viene y, si no viene o la descarga falla, consulta el media id.<\/p>\n\n\n\n
    Campo<\/th>Para qu\u00e9 sirve<\/th><\/tr><\/thead>
    id<\/code><\/td>Media id; \u00fasalo para generar la URL de descarga<\/td><\/tr>
    mime_type<\/code><\/td>Tipo de archivo (image\/jpeg<\/code>, application\/pdf<\/code>, audio\/ogg<\/code>…)<\/td><\/tr>
    sha256<\/code><\/td>Hash del archivo, para verificar integridad<\/td><\/tr>
    caption<\/code><\/td>Texto que envi\u00f3 el cliente con el archivo, si lo hay<\/td><\/tr>
    filename<\/code><\/td>Nombre original (documentos)<\/td><\/tr>
    url<\/code><\/td>URL de descarga directa, en habilitaci\u00f3n gradual<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Tipos y l\u00edmites de tama\u00f1o<\/h2>\n\n\n\n
    La tabla resume los tipos admitidos y los tama\u00f1os m\u00e1ximos de la p\u00e1gina de multimedia de Meta. Sirve para dimensionar el almacenamiento y el tiempo l\u00edmite de descarga:<\/p>\n\n\n\n
    Tipo<\/th>Formatos<\/th>Tama\u00f1o m\u00e1ximo<\/th><\/tr><\/thead>
    Audio<\/td>AAC, AMR, MP3, M4A, OGG (solo c\u00f3dec OPUS, mono)<\/td>16 MB<\/td><\/tr>
    Documento<\/td>TXT, XLS, XLSX, DOC, DOCX, PPT, PPTX, PDF<\/td>100 MB<\/td><\/tr>
    Imagen<\/td>JPEG, PNG (8 bits, RGB o RGBA)<\/td>5 MB<\/td><\/tr>
    Sticker<\/td>WebP<\/td>500 KB animado, 100 KB est\u00e1tico<\/td><\/tr>
    Video<\/td>3GP, MP4 (H.264 y AAC)<\/td>16 MB<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Las notas de voz llegan como mensajes de tipo audio<\/code>. Si vas a pasar el audio a un servicio de transcripci\u00f3n, revisa el mime_type<\/code> recibido y si el servicio acepta ese formato; si no, convi\u00e9rtelo antes.<\/p>\n\n\n\n
    Ejemplo con cURL<\/h2>\n\n\n\n
    Paso 2, obtener la 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
    Respuesta:<\/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
    Paso 3, descargar:<\/p>\n\n\n\n
    curl -L \"URL_DEVUELTA\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -o comprobante.jpg<\/code><\/pre>\n\n\n\n
    Opcionalmente, env\u00eda phone_number_id<\/code> como par\u00e1metro de consulta en el paso 2: as\u00ed Meta solo procesa la solicitud si el archivo pertenece a ese n\u00famero, una protecci\u00f3n \u00fatil cuando la misma aplicaci\u00f3n atiende varios n\u00fameros.<\/p>\n\n\n\n
    Ejemplo en 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 obtenerUrl(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 descargar(url) {\n  const res = await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } });\n  if (!res.ok) throw Object.assign(new Error('descarga fallida'), { status: res.status });\n  return Buffer.from(await res.arrayBuffer());\n}\n\nexport async function guardarArchivo(media, clave) {\n  let info = { url: media.url, sha256: media.sha256, mime_type: media.mime_type };\n  let archivo;\n  try {\n    if (!info.url) throw new Error('sin url en el webhook');\n    archivo = await descargar(info.url);\n  } catch {\n    info = await obtenerUrl(media.id); \/\/ genera una URL nueva\n    archivo = await descargar(info.url);\n  }\n\n  const hash = crypto.createHash('sha256').update(archivo).digest('base64');\n  if (info.sha256 && hash !== info.sha256) throw new Error('el hash no coincide');\n\n  await s3.send(new PutObjectCommand({\n    Bucket: process.env.BUCKET,\n    Key: clave,\n    Body: archivo,\n    ContentType: info.mime_type,\n  }));\n  return clave;\n}<\/code><\/pre>\n\n\n\n
    En los ejemplos de Meta, el sha256<\/code> viene en base64; por eso la comparaci\u00f3n usa digest('base64')<\/code>. Si en tu caso ves otro formato, registra ambos valores antes de activar la verificaci\u00f3n.<\/p>\n\n\n\n
    Ejemplo en 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 obtener_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 guardar_archivo(media: dict, clave: str) -> str:\n    with httpx.Client(timeout=60, follow_redirects=True) as client:\n        info = obtener_url(client, media[\"id\"])\n        r = client.get(info[\"url\"], headers=HEADERS)\n        if r.status_code == 404:  # URL vencida: genera otra y reintenta\n            info = obtener_url(client, media[\"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(\"el hash no coincide\")\n\n    s3.put_object(\n        Bucket=os.environ[\"BUCKET\"],\n        Key=clave,\n        Body=r.content,\n        ContentType=info[\"mime_type\"],\n    )\n    return clave<\/code><\/pre>\n\n\n\n
    Para documentos de hasta 100 MB, cargar todo en memoria puede pesar. En ese caso, descarga en stream<\/em> a un archivo temporal y usa upload_fileobj<\/code> de boto3, o Upload<\/code> del paquete @aws-sdk\/lib-storage<\/code> en Node, que suben por partes.<\/p>\n\n\n\n
    D\u00f3nde va esto en la arquitectura<\/h2>\n\n\n\n
    No descargues el archivo dentro de la solicitud del webhook. El endpoint debe validar la firma, encolar el evento y responder 200<\/code> r\u00e1pido; un worker aparte hace la descarga y la carga. As\u00ed, un video grande no bloquea el webhook ni provoca reintentos de Meta. Sobre la validaci\u00f3n, consulta c\u00f3mo validar la firma del webhook<\/a>.<\/p>\n\n\n\n
    Algunas buenas pr\u00e1cticas:<\/p>\n\n\n\n