Como gerenciar contatos pela API do WhatsApp

A API do WhatsApp permite listar contatos, consultar o perfil público de um número e bloquear ou desbloquear — os mesmos recursos de gestão de contato do app, só que por código. Este tutorial mostra o passo a passo de cada ação, com os casos em que vale automatizar.

Por que gerenciar contato por código

Times que operam atendimento em volume raramente abrem o WhatsApp Web para checar um contato manualmente — a informação precisa estar disponível dentro do próprio sistema que já gerencia a conversa. Listar e consultar perfil pela API é o que alimenta esse tipo de painel interno sem depender de olhar o app.

Bloqueio automatizado, por sua vez, é a resposta técnica para abuso recorrente — spam, tentativa de golpe se passando por outro contato — que numa operação de suporte manual demoraria até alguém perceber e agir.

Essas três ações — listar, consultar e bloquear/desbloquear — cobrem o ciclo básico de gestão de contato que a maioria das integrações precisa. Times maiores costumam combinar isso com um sistema próprio de histórico, já que a API entrega o estado atual do contato, não um registro histórico de mudanças ao longo do tempo.

Pré-requisitos

• Instância conectada via QR Code ou pareamento.
• Acesso à key da instância para autenticar as chamadas.

Passo a passo

1. Liste todos os contatos

curl https://us.api-wa.me/{KEY}/contacts

A resposta traz a lista de contatos salvos na instância — útil para popular um painel interno ou sincronizar com um CRM, no mesmo espírito de quem já organiza conversa por etiqueta.

2. Consulte o perfil de um contato específico

curl https://us.api-wa.me/{KEY}/contacts/5511999999999

Isso retorna os dados públicos daquele número — nome de exibição e foto de perfil, quando a privacidade do contato permite. Útil para confirmar identidade antes de uma ação sensível, como iniciar uma cobrança ou uma chamada (veja WhatsApp Calling API para o próximo passo depois de confirmar quem é o contato).

3. Bloqueie um contato

curl -X PATCH "https://us.api-wa.me/{KEY}/contacts/5511999999999?action=block"

O número bloqueado não consegue mais mandar mensagem para a instância — o mesmo efeito de bloquear manualmente pelo app.

4. Desbloqueie quando necessário

curl -X PATCH "https://us.api-wa.me/{KEY}/contacts/5511999999999?action=unblock"

Reverte o bloqueio, liberando o número para voltar a enviar mensagem.

5. Automatize o bloqueio por critério

Um caso de uso direto: seu sistema já detecta um padrão de abuso (mensagem repetida em alta frequência, tentativa de golpe reportada por outro cliente). Em vez de esperar uma ação manual, o mesmo evento que detecta o abuso chama o bloqueio:

async function bloquearPorAbuso(numero) {
  await fetch(`https://us.api-wa.me/${KEY}/contacts/${numero}?action=block`, {
    method: 'PATCH',
  });
  // registrar o bloqueio no seu sistema, com motivo e data
}

Registrar o motivo do bloqueio junto da ação é o que permite auditar depois — sem esse registro, um bloqueio automatizado vira uma decisão que ninguém consegue explicar meses depois.

Sincronizando contatos com seu sistema

Listar contatos pela API costuma ser o primeiro passo de uma sincronização maior — trazer os contatos do WhatsApp para dentro do seu CRM ou painel próprio, evitando manter duas fontes de verdade desalinhadas.

async function sincronizarContatos() {
  const resp = await fetch(`https://us.api-wa.me/${KEY}/contacts`);
  const contatos = await resp.json();

  for (const contato of contatos) {
    await upsertNoBanco({
      numero: contato.id,
      nome: contato.name || contato.pushname,
      atualizadoEm: new Date().toISOString(),
    });
  }
}

Rodar essa sincronização periodicamente (uma vez por dia costuma bastar para a maioria dos casos) mantém seu sistema interno alinhado sem precisar consultar a API a cada tela aberta por um atendente.

Consultando perfil antes de uma ação sensível

Confirmar quem é o contato antes de uma ação que não pode ser desfeita facilmente — iniciar uma cobrança, uma chamada, ou enviar um documento com dado sensível — reduz o risco de erro de digitação no número:

async function confirmarAntesDeAgir(numero) {
  const resp = await fetch(`https://us.api-wa.me/${KEY}/contacts/${numero}`);
  const perfil = await resp.json();

  if (!perfil || !perfil.name) {
    // número sem perfil reconhecível: exige confirmação manual antes de prosseguir
    return false;
  }
  return true;
}

Esse tipo de checagem é barato de implementar e evita o cenário mais caro de corrigir: uma mensagem sensível enviada para o número errado por um dígito trocado na digitação.

Combinando com o histórico de conversa

Perfil de contato e bloqueio são pontuais — dizem o estado agora. Para decisões que dependem de contexto ao longo do tempo (esse contato já reclamou antes? já foi bloqueado e desbloqueado alguma vez?), o ideal é que seu sistema mantenha esse histórico por conta própria, já que a API não guarda esse tipo de registro retroativo — ela reflete o estado atual do WhatsApp, não um log de mudanças.

Erros comuns

Bloquear com base em um único evento isolado. Uma mensagem fora do padrão não é necessariamente abuso — pode ser um cliente legítimo com um problema real. Vale um critério de repetição ou gravidade antes de automatizar o bloqueio, não a primeira ocorrência.

Não ter caminho de desbloqueio. Todo fluxo de bloqueio automático precisa de uma forma de reverter — um contato bloqueado por engano, sem caminho de correção, é um cliente perdido por um falso positivo do seu critério de detecção.

Confundir bloqueio de contato com moderação de grupo. Bloquear um número na instância impede conversa direta com aquele contato; para tirar alguém de um grupo, a ação é outra — remover participante, coberta em automatizar grupos de WhatsApp pela API.

Não considerar o impacto de bloquear um número compartilhado. Alguns contatos usam o mesmo número para uso pessoal e profissional. Bloquear com base num evento isolado, sem investigar o contexto, pode cortar de vez um canal de comunicação que tinha outros usos legítimos além do que gerou o bloqueio.

Diferença entre bloquear contato e opt-out de campanha

Vale não confundir os dois mecanismos, porque resolvem problemas diferentes:

Bloquear é uma ação defensiva contra abuso vindo do contato; opt-out é uma ação de respeito à preferência do contato de não receber mais determinado tipo de mensagem sua. Um contato pode pedir opt-out sem nunca precisar ser bloqueado, e vice-versa — tratar os dois como a mesma coisa mistura um problema de segurança com um problema de consentimento. O processo de opt-out está detalhado em lista de contatos para WhatsApp: opt-in, higienização e opt-out automático.

Frequência recomendada de sincronização

Para operações pequenas, sincronizar contatos uma vez por dia é suficiente. Para operações com alta rotatividade de novos contatos — um número de vendas que recebe leads o dia todo, por exemplo — vale reduzir esse intervalo ou, melhor ainda, disparar a sincronização de um contato específico assim que ele manda a primeira mensagem, capturada pelo próprio webhook, em vez de esperar a próxima rodada agendada.

Próximos passos

Depois de gerenciar contato individualmente, o próximo nível de organização é por conversa — veja como gerenciar chats pela API para listar, marcar como lido e fixar. Para times que já pensam em organização por estágio de relacionamento, Labels na API do WhatsApp complementa a gestão de contato com um sistema de etiquetas.