Validar un número de WhatsApp por API: cómo saber si el número tiene WhatsApp

Formato: ¿el número tiene código de país, código de área válido y la cantidad correcta de dígitos? Es una regla de texto, que corre en tu navegador o servidor sin consultar a nadie. La herramienta gratis para validar números de WhatsApp y el formateador en lote hacen esto, incluido el noveno dígito del celular brasileño.

Existencia: ¿ese número, aunque esté bien formado, está registrado en WhatsApp ahora? Solo una consulta a WhatsApp lo responde. Por eso la herramienta de formato avisa que no confirma que la cuenta exista, y la verificación llega por la API.

En la API de ZapZap, el endpoint es POST /api/v1/{instanceId}/chat/check, con el campo numbers como lista. La respuesta trae, para cada número consultado, el campo query (lo que enviaste), isInWhatsapp (verdadero o falso) y jid (el identificador de la conversación). La descripción completa está en la referencia del endpoint.

Envía el número en el mismo formato del envío: código de país y solo dígitos. Revisa el formato de la respuesta con dos números tuyos antes de conectarlo a tu flujo.

# Does this number have WhatsApp?
curl -X POST "https://api.zapzapapi.com/api/v1/$ZAPZAP_INSTANCE/chat/check" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"numbers":["5511999999999","5521888888888"]}'
# Each item of the answer carries: query, isInWhatsapp (true/false) and jid

El ejemplo normaliza el formato (solo dígitos, código de país 55 cuando falta, descarte de lo que no puede ser un número brasileño), elimina duplicados, consulta en lotes pequeños con pausa y devuelve solo a quienes tienen WhatsApp. El resultado alimenta el envío siguiente y reduce errores.

La regla de normalización es simple a propósito. Para casos límite, como el noveno dígito en números antiguos, usa el formateador del sitio como referencia.

// Validate a small batch before sending, keep only numbers that exist
const API = "https://api.zapzapapi.com/api/v1/" + process.env.ZAPZAP_INSTANCE;
const headers = {
  "Content-Type": "application/json",
  "x-api-key": process.env.ZAPZAP_API_KEY,
  "x-api-secret": process.env.ZAPZAP_API_SECRET,
};

export function normalizeBr(raw) {
  // 1) digits only, 2) add country code 55 when missing, 3) reject what cannot be a Brazilian number
  let d = String(raw).replace(/\D/g, "");
  if (d.length === 10 || d.length === 11) d = "55" + d;
  return /^55\d{10,11}$/.test(d) ? d : null;
}

export async function filterWhatsApp(rawNumbers) {
  const numbers = [...new Set(rawNumbers.map(normalizeBr).filter(Boolean))];
  const ok = [];
  for (let i = 0; i < numbers.length; i += 20) {           // small batches
    const batch = numbers.slice(i, i + 20);
    const r = await fetch(API + "/chat/check", { method: "POST", headers, body: JSON.stringify({ numbers: batch }) });
    if (!r.ok) throw new Error("check failed: HTTP " + r.status);
    const items = await r.json();
    for (const it of items) if (it.isInWhatsapp) ok.push({ number: it.query, jid: it.jid });
    await new Promise((res) => setTimeout(res, 3000 + Math.random() * 4000)); // pause between batches
  }
  return ok;
}

Consultar miles de números a la vez, en ráfaga, es un patrón de comportamiento inusual. No tenemos un límite publicado para este endpoint, así que el consejo prudente es el mismo del envío: lotes pequeños, pausa entre ellos y nada en paralelo. Si tu lista es grande, valida primero el formato (gratis, local) y consulta la existencia solo de quienes pasaron.

Guarda el resultado con la fecha de la consulta. Un número que hoy tiene WhatsApp puede no tenerlo mañana, y uno sin WhatsApp puede crearse después. Y recuerda que tener WhatsApp no significa haber consentido recibir tu mensaje: mira LGPD en WhatsApp.

El punto más útil es el registro: valida cuando el lead escribe el teléfono y avisa al instante si el número no tiene WhatsApp, en vez de descubrirlo en el envío. El segundo es la limpieza de una base antigua, antes de reactivarla. En ambos, combínalo con el calentamiento y con un volumen gradual.

Si usas n8n, el endpoint cabe en un nodo HTTP Request antes del nodo de envío. La guía de WhatsApp en n8n muestra el diseño del flujo.