WhatsApp se desconecta solo en la API: causas y solución

Empieza por el status de la instancia. La respuesta trae el estado actual (disconnected, connecting o connected) y, en instancias desconectadas, campos como lastDisconnect y lastDisconnectReason, que registran cuándo y por qué motivo terminó la conexión (por ejemplo, una desconexión pedida por la propia API). No es una lista cerrada de motivos: trata el texto como una pista y cruza la información con la tabla de abajo.

Después mira tu lado. ¿Alguien del equipo llamó a desconectar instancia o a reiniciar instancia? Un script de mantenimiento, una prueba automatizada o una automatización mal diseñada que llama a desconectar en bucle explican muchos casos de caídas recurrentes.

curl "https://api.zapzapapi.com/api/v1/$INSTANCE_ID/instance/status" \
  -H "x-api-key: $ZAPZAP_API_KEY" \
  -H "x-api-secret: $ZAPZAP_API_SECRET"
# veja instance.status e, quando houver, instance.lastDisconnect e instance.lastDisconnectReason

Sobre el saldo: ZapZap suspende las instancias cuando el saldo no cubre la renovación pasado el período de gracia, y la reactivación tras el pago deja la instancia desconectada, lo que exige una nueva vinculación. Por eso mantener el saldo con holgura evita la caída. Los detalles de cobro están en precios.

Sobre el celular: la conexión de dispositivos adicionales depende del dispositivo principal. Si el WhatsApp del celular principal pasa mucho tiempo sin uso, WhatsApp puede cerrar las sesiones vinculadas. Consulta el artículo 'Acerca de los dispositivos vinculados' en el Centro de ayuda de WhatsApp para ver las reglas actuales, porque cambian.

Si la instancia quedó desconectada, el camino es vincular de nuevo: pide el QR en QR Code de la instancia o usa la vinculación por código en conectar instancia. El paso a paso y los códigos de error están en la guía de QR que no aparece.

Si la instancia aparece conectada pero no responde, reiniciar el runtime puede resolverlo. No borra tu configuración. Si la instancia está desconectada, el reinicio no reemplaza a la vinculación: habrá que leer el QR de nuevo. Registra cada reconexión con fecha y motivo; tres caídas en la misma semana piden investigar la causa, no solo reconectar.

BASE="https://api.zapzapapi.com/api/v1"
H1="x-api-key: $ZAPZAP_API_KEY"
H2="x-api-secret: $ZAPZAP_API_SECRET"

curl -X POST "$BASE/$INSTANCE_ID/instance/reset" -H "$H1" -H "$H2"
sleep 10
curl "$BASE/$INSTANCE_ID/instance/status" -H "$H1" -H "$H2"

Activa el evento connection en el webhook. Se dispara con cada cambio de estado del número (conectado, desconectado, conectando). Al recibir desconectado, tu sistema puede abrir una alerta para el equipo, pausar las colas de envío y, si la regla de negocio lo permite, avisar al cliente final que la atención está inestable. La configuración está en configurar webhook, y el tratamiento seguro del evento, en la guía de webhook en producción.

Como segunda red, haz una verificación periódica del status de la instancia. Un webhook puede fallar, y un monitor simple que consulte el status cada pocos minutos y alerte ante una caída cubre ese hueco. Si usas n8n, la integración con n8n trae el disparador de webhook listo para esa automatización.

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

async function checar(id) {
  const resp = await fetch(BASE + "/" + id + "/instance/status", { headers });
  if (!resp.ok) return console.error("status falhou", resp.status);
  const { instance } = await resp.json();
  if (instance.status !== "connected") {
    console.error("ALERTA: instância", id, "está", instance.status, instance.lastDisconnectReason || "");
    // aqui: enviar e-mail, Slack, etc.
  }
}

setInterval(() => checar(process.env.INSTANCE_ID).catch(console.error), 3 * 60 * 1000);

Las caídas recurrentes tienen menos que ver con la suerte y más con el proceso. Ten un responsable del celular del número, mantén la aplicación actualizada, no elimines el dispositivo vinculado sin avisar a la operación y evita usar el mismo número en otra herramienta al mismo tiempo. Para operaciones donde el número es crítico, ten un número de respaldo y separa funciones (atención, cobranza, ventas) en instancias distintas, de modo que una caída no detenga todo.

Si la desconexión vino acompañada de una restricción de WhatsApp, no es una falla técnica que se arregle con un reinicio. Ninguna herramienta elimina ese riesgo, y el uso de una API no oficial no está previsto en los Términos de WhatsApp. La guía de antibloqueo en WhatsApp explica qué reduce el riesgo y qué no lo elimina.

[ ] Hay un responsable del celular del número y de mantener la aplicación actualizada

[ ] Nadie elimina el dispositivo vinculado sin avisar a la operación

[ ] El saldo cubre la renovación con holgura

[ ] Los scripts y automatizaciones no llaman a desconectar o reiniciar sin necesidad

[ ] El evento connection está activado en el webhook y alerta al equipo

[ ] Existe un monitor de status como segunda red

[ ] Hay un número de respaldo y un canal alternativo para avisar a los clientes

Cada caída que se repite es un dato. Anota la fecha, la hora, el lastDisconnectReason y qué cambió ese día (deploy, cambio de celular, campaña). En pocas semanas aparece el patrón, y casi siempre es una causa operativa que se resuelve con proceso y no con tecnología.