Cómo recibir y descargar audio, imagen y PDF de WhatsApp por webhook

Son tres pasos. Uno: el evento messages llega a tu webhook con el mensaje; cuando hay multimedia, el evento describe el tipo y trae el ID del mensaje. Dos: tu servidor llama a /message/download con ese id. Tres: copias el archivo a tu almacenamiento y lo procesas.

La separación existe por un motivo práctico: el webhook debe ser liviano y responder 2xx rápido, y un archivo es pesado. Por eso el webhook entrega el aviso, y la descarga ocurre en tu worker, fuera del camino de la respuesta HTTP. Para el diseño general del webhook, mira la guía de webhook en producción.

Registra la URL pública (HTTPS) de la instancia con POST a /webhook, enviando url, enabled y la lista events. Los eventos vienen desactivados por defecto; para multimedia, activa messages. Los eventos de alto volumen como presence e history solo actívalos si vas a tratarlos.

Prueba la entrega con POST /instances/{id}/webhook/test: envía un evento de prueba e informa el status HTTP y el tiempo de respuesta de tu endpoint. Si algo no llega, GET /instances/{id}/webhook/deliveries muestra las últimas entregas y GET /webhook/errors lista las fallas.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"url":"https://seu-servidor.com/webhook/whatsapp","enabled":true,"events":["messages"]}'

La forma exacta del payload debe comprobarse en un evento real de tu instancia: guarda el cuerpo crudo en un log, envía desde el celular una foto, un audio y un PDF y compara. Los nombres de campo varían según el tipo de mensaje, y es mejor mapear a partir de lo que viste que de un ejemplo genérico.

Lo que necesitas extraer en todos los casos: el ID del mensaje, el tipo (texto, imagen, audio, documento), el remitente y si el mensaje lo enviaste tú (fromMe). Descarta fromMe al comienzo. Los ejemplos de abajo usan lectura defensiva con valores alternativos; ajusta los nombres después de ver tu payload.

La llamada recibe id y flags opcionales. Con return_link true (por defecto), la respuesta trae fileURL y mimetype. Con return_base64 true, trae el contenido en base64 en la propia respuesta; úsalo solo para archivos pequeños. generate_mp3 convierte el audio a MP3 y transcribe pide la transcripción, que la documentación describe como best-effort y puede no venir.

El servidor de abajo responde 200 antes de descargar, extrae el ID, llama a la descarga y escribe el archivo en disco. En producción, cambia la escritura en disco por una subida a tu almacenamiento de objetos y no trates la fileURL como permanente: copia el archivo a tu lado.

import express from "express";
import { writeFile } from "node:fs/promises";

const app = express();
app.use(express.json({ limit: "2mb" }));

const BASE = "https://api.zapzapapi.com/api/v1/" + process.env.ZAPZAP_INSTANCE_ID;
const headers = {
  "Content-Type": "application/json",
  "x-api-key": process.env.ZAPZAP_API_KEY,
  "x-api-secret": process.env.ZAPZAP_API_SECRET,
};

app.post("/webhook/whatsapp", (req, res) => {
  res.sendStatus(200);
  tratar(req.body).catch((e) => console.error("handler error", e));
});

async function tratar(evento) {
  const msg = evento?.message ?? evento?.data ?? evento;
  if (msg?.fromMe) return;

  const id = msg?.messageid ?? msg?.id;
  const tipo = String(msg?.messageType ?? msg?.type ?? "");
  if (!id || !/image|audio|ptt|document|video/i.test(tipo)) return;

  const r = await fetch(BASE + "/message/download", {
    method: "POST",
    headers,
    body: JSON.stringify({ id, return_link: true }),
  });
  if (!r.ok) throw new Error("download failed " + r.status + ": " + (await r.text()));
  const { fileURL, mimetype } = await r.json();

  const arquivo = await fetch(fileURL);
  const bytes = Buffer.from(await arquivo.arrayBuffer());
  const ext = (mimetype || "application/octet-stream").split("/")[1]?.split(";")[0] || "bin";
  await writeFile("./midia-" + id.replace(/[^a-zA-Z0-9_-]/g, "_") + "." + ext, bytes);
}

app.listen(3000);

La misma lógica en Python con Flask y requests. El punto de atención es el mismo: responder rápido y descargar en segundo plano. El ejemplo usa un hilo simple para ser corto; en producción usa una cola (Celery, RQ, Cloud Tasks o equivalente).

Si solo necesitas el texto de un audio, pide transcribe true en la llamada de descarga, sabiendo que es best-effort, o usa el módulo de IA de la instancia para una transcripción garantizada, como indica la propia referencia del endpoint.

import os
import threading
import requests
from flask import Flask, request

app = Flask(__name__)
BASE = "https://api.zapzapapi.com/api/v1/" + os.environ["ZAPZAP_INSTANCE_ID"]
HEADERS = {
    "Content-Type": "application/json",
    "x-api-key": os.environ["ZAPZAP_API_KEY"],
    "x-api-secret": os.environ["ZAPZAP_API_SECRET"],
}


def tratar(evento):
    msg = evento.get("message") or evento.get("data") or evento
    if msg.get("fromMe"):
        return
    msg_id = msg.get("messageid") or msg.get("id")
    tipo = str(msg.get("messageType") or msg.get("type") or "")
    if not msg_id or not any(t in tipo.lower() for t in ("image", "audio", "ptt", "document", "video")):
        return

    r = requests.post(BASE + "/message/download", json={"id": msg_id, "return_link": True}, headers=HEADERS, timeout=60)
    r.raise_for_status()
    dados = r.json()

    arquivo = requests.get(dados["fileURL"], timeout=60)
    arquivo.raise_for_status()
    ext = dados.get("mimetype", "application/octet-stream").split("/")[-1].split(";")[0]
    with open("midia-%s.%s" % (str(msg_id).replace(":", "_"), ext), "wb") as f:
        f.write(arquivo.content)


@app.post("/webhook/whatsapp")
def webhook():
    threading.Thread(target=tratar, args=(request.get_json(force=True),), daemon=True).start()
    return "", 200

Si perdiste el evento (servidor caído, por ejemplo), recupera el mensaje con POST /message/find. Filtra por id para un mensaje específico o por chatid para el historial de una conversación, con limit y offset para paginar. Luego usa el id devuelto en /message/download.

Esto también resuelve el reprocesamiento: si la descarga falló, el id quedó guardado y repites la llamada después, sin depender de un nuevo evento del webhook.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/message/find \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"chatid":"5511999999999@s.whatsapp.net","limit":20,"offset":0}'

Ante la duda, empieza por return_link y trata lo demás como optimización. El PDF y la imagen no necesitan conversión; el audio de voz suele ser el único que pide MP3 para sonar en cualquier lugar.

En producción, el endpoint del webhook hace tres cosas y solo tres: valida el formato del evento, guarda el id del mensaje y el tipo en una cola (base de datos, Redis, cola gestionada) y responde 2xx. Un worker aparte consume la cola, llama a /message/download, copia el archivo a tu almacenamiento y marca el ítem como concluido.

Este diseño resuelve tres problemas a la vez. Una descarga fallida se vuelve un reintento con backoff sin perder el evento. Un pico de mensajes (una campaña que genera muchas respuestas) no tumba el endpoint. Y la deduplicación queda simple: el id del mensaje es la clave única de la cola, y un segundo evento igual se ignora.

Idempotencia: el mismo evento puede llegar dos veces. Guarda el id del mensaje e ignora los ya procesados, para no descargar ni procesar el mismo archivo dos veces. Seguridad: trata todo archivo recibido como no confiable. Valida el tipo real del archivo (no solo la extensión), limita el tamaño y nunca ejecutes ni abras documentos en el servidor sin antivirus o aislamiento.

Privacidad: el audio, la foto y el PDF de los clientes son datos personales y pueden ser sensibles. Define por cuánto tiempo los guardas, quién accede y cómo se borran, y registra la base legal según la ley de protección de datos. La guía de envío masivo y protección de datos trae el razonamiento general. Para depurar la entrega del webhook, consulta la documentación de webhooks y la referencia de message/download.