Como verificar se um número tem WhatsApp pela API (antes de enviar)

Para saber se um número tem WhatsApp antes de enviar, faça um GET /{key}/actions/registered?number=... na API não oficial da WAME: a resposta diz se o número está registrado e devolve o JID dele. Nada chega ao celular da pessoa. O lugar certo para usar isso é no cadastro do cliente e na manutenção da sua própria base — não para varrer números desconhecidos, que é abuso e um dos jeitos mais rápidos de perder o número.

Neste guia você vê o endpoint, três lugares onde ele economiza dinheiro e dor de cabeça, e as regras de ritmo que mantêm a sua conta saudável.

Por que verificar antes de enviar

Telefone digitado errado é o erro mais comum de qualquer cadastro. Um dígito a menos, um 9 esquecido, um fixo no campo de celular — e a mensagem de confirmação de pedido nunca chega. O cliente acha que a loja não respondeu; a loja acha que avisou.

Verificar o número resolve três problemas de uma vez:

• Erro de digitação vira aviso na hora, enquanto a pessoa ainda está no formulário.
• Menos envio para o vazio. Envio que falha não ajuda ninguém e polui suas métricas.
• Base limpa. Você sabe quais contatos podem ser atendidos pelo WhatsApp e quais precisam de e-mail ou SMS.

A camada não oficial da WAME é independente e não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

O endpoint

É um GET simples, com o número na query string:

curl "https://us.api-wa.me/SUA_KEY/actions/registered?number=5511999999999"

A resposta informa se o número está no WhatsApp e, quando está, traz o JID — o identificador no formato [email protected]. O formato exato do retorno está na documentação.

Um detalhe que vale ouro no Brasil: por causa do nono dígito, alguns números antigos estão registrados no WhatsApp sem o 9 extra. O JID devolvido pela verificação é o identificador real — guarde ele, e não o que a pessoa digitou.

Normalize antes de consultar

Metade dos "números sem WhatsApp" são números mal formatados. Antes de chamar a API, limpe:

function normalizarTelefoneBR(entrada) {
  let d = String(entrada).replace(/\D/g, '');   // só dígitos
  if (d.startsWith('0')) d = d.replace(/^0+/, ''); // tira zero de operadora/DDD
  if (d.length === 10 || d.length === 11) d = '55' + d; // sem país → Brasil
  return d;
}

normalizarTelefoneBR('(11) 99999-9999'); // "5511999999999"
normalizarTelefoneBR('+55 21 98888-8888'); // "5521988888888"

Para uma base internacional, use uma biblioteca como libphonenumber-js em vez de regras caseiras.

Uso 1: validação no formulário de cadastro

O melhor momento para verificar é quando a pessoa ainda está na tela. Um exemplo de rota no seu backend (Node.js + Express):

const BASE = 'https://us.api-wa.me/SUA_KEY';

app.post('/api/validar-whatsapp', async (req, res) => {
  const numero = normalizarTelefoneBR(req.body.telefone);

  const r = await fetch(`${BASE}/actions/registered?number=${numero}`);
  if (!r.ok) return res.status(502).json({ erro: 'falha ao verificar' });

  const dados = await r.json();
  // Confira na documentação o campo exato que indica o registro
  // e o campo com o JID, e guarde o JID no cadastro do cliente.
  res.json({ numero, resultado: dados });
});

No front, chame essa rota quando o campo perde o foco e mostre um aviso gentil: "Não encontramos WhatsApp neste número. Confere se está certo?". Não bloqueie o cadastro — a pessoa pode preferir e-mail — mas avise.

Duas regras importantes aqui:

1. A chamada sai do seu backend, nunca do navegador. A key da instância autentica tudo; exposta no front, qualquer um usa a sua instância. Mais sobre isso em segurança da API do WhatsApp.
2. Proteja a rota com rate limit e captcha. Senão alguém transforma o seu formulário numa máquina de consultar números — e quem paga é o seu número.

Uso 2: higienizar a base do CRM

Você tem uma base de clientes que se cadastraram ao longo dos anos. Antes de ligar a automação de avisos, faz sentido saber quem tem WhatsApp. O jeito certo é devagar:

const esperar = (ms) => new Promise((r) => setTimeout(r, ms));

async function higienizar(clientes) {
  for (const c of clientes) {
    const numero = normalizarTelefoneBR(c.telefone);
    const r = await fetch(`${BASE}/actions/registered?number=${numero}`);
    c.whatsapp = r.ok ? await r.json() : null;
    await salvar(c);

    // Intervalo variável entre consultas: ritmo de gente, não de script
    await esperar(3000 + Math.random() * 4000);
  }
}

É lento de propósito. Uma base de alguns milhares de contatos leva horas — rode em segundo plano, fora do horário de pico, e em lotes ao longo de dias se a base for grande. Lembre que esses contatos são seus clientes, que deram o telefone para você; higienizar não substitui ter o consentimento deles para receber mensagens. O processo completo de opt-in está em lista de contatos para WhatsApp: opt-in e opt-out.

Uso 3: antes do primeiro envio de uma automação

Em fluxos automáticos — confirmação de pedido, lembrete de consulta — verificar o número uma vez, no primeiro contato, e guardar o JID evita repetir a consulta a cada mensagem. A regra é simples: verifica uma vez, salva, reusa. Se o envio falhar lá na frente, aí sim vale verificar de novo (a pessoa pode ter trocado de número).

O que não fazer: varrer números

Existe um uso desse endpoint que a WAME não apoia e que derruba números com frequência: gerar sequências de telefones (11999990000, 11999990001, ...) ou comprar listas e consultar em massa para "descobrir quem tem WhatsApp" e depois disparar mensagens.

Isso é ruim por três motivos:

• É spam na origem. Ninguém ali pediu para falar com você. A WAME não apoia spam, e esse é o começo de toda operação de spam.
• É um padrão fácil de detectar. Milhares de consultas a números que não estão na sua agenda, em rajada, não se parecem com nenhum uso humano do WhatsApp.
• Viola a LGPD. Consultar e tratar dados de telefones de pessoas sem relação com você não tem base legal.

A WAME protege a sessão com uma camada de comportamento — limites de ritmo, identidade de dispositivo coerente com o país, reconexão espaçada — e por isso a taxa de bloqueio é muito baixa para quem usa do jeito certo. Mas nenhuma camada técnica disfarça uma varredura de números. Os detalhes estão em anti-detecção na API não oficial, e o que de fato derruba um número em a API não oficial bane? O que derruba um número.

Boas práticas resumidas

Conclusão

Verificar se um número tem WhatsApp pela API é uma das funções mais simples e mais úteis da API não oficial: um GET /{key}/actions/registered pega o erro de digitação no cadastro, limpa a sua base e evita envios para o vazio. Usado com o ritmo certo e só com contatos que são seus, ele deixa a operação mais eficiente sem colocar o número em risco. Veja outros recursos em API não oficial do WhatsApp: recursos e exemplos e o formato completo da resposta na documentação.