Validar número de WhatsApp via API: como saber se o número tem WhatsApp

Formato: o número tem DDI, DDD válido e o total de dígitos certo? É uma regra de texto, que roda no seu navegador ou servidor sem consultar ninguém. A ferramenta grátis de validar número de WhatsApp e o formatador em lote fazem isso, inclusive o nono dígito do celular brasileiro.

Existência: aquele número, mesmo bem formado, está registrado no WhatsApp agora? Só uma consulta ao WhatsApp responde. Por isso a ferramenta de formato avisa que não confirma se a conta existe, e a verificação vem pela API.

Na ZapZap API, o endpoint é POST /api/v1/{instanceId}/chat/check, com o campo numbers como lista. A resposta traz, para cada número consultado, o campo query (o que você enviou), isInWhatsapp (verdadeiro ou falso) e jid (o identificador da conversa). A descrição completa está na referência do endpoint.

Mande o número no mesmo formato do envio: DDI e só dígitos. Confira o formato da resposta com dois números seus antes de ligar isso no seu fluxo.

# 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

O exemplo normaliza o formato (apenas dígitos, DDI 55 quando faltar, descarte do que não pode ser número brasileiro), remove duplicados, consulta em lotes pequenos com pausa e devolve só quem tem WhatsApp. O resultado alimenta o envio seguinte e reduz erros.

A regra de normalização é simples de propósito. Para casos de borda, como o nono dígito em números antigos, use o formatador do site como referência.

// 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 milhares de números de uma vez, em rajada, é um padrão de comportamento incomum. Não temos limite publicado para esse endpoint, então o conselho prudente é o mesmo do envio: lotes pequenos, pausa entre eles e nada em paralelo. Se a sua lista é grande, valide o formato primeiro (grátis, local) e só consulte a existência de quem passou.

Guarde o resultado com a data da consulta. Número que tinha WhatsApp hoje pode não ter amanhã, e número sem WhatsApp pode ser criado depois. E lembre que ter WhatsApp não significa ter consentido em receber a sua mensagem: veja LGPD no WhatsApp.

O ponto mais útil é o cadastro: valide quando o lead digita o telefone, e avise na hora se o número não tem WhatsApp, em vez de descobrir no disparo. O segundo é a limpeza de uma base antiga, antes de reativá-la. Em ambos, combine com o aquecimento e com um volume gradual.

Se você usa n8n, o endpoint cabe num nó de HTTP Request antes do nó de envio. O guia de WhatsApp no n8n mostra o desenho do fluxo.