---
title: "Como gerenciar contatos pela API do WhatsApp"
description: "Tutorial: como listar contatos, consultar perfil e bloquear/desbloquear pela API do WhatsApp — passo a passo com exemplos em cURL e casos de uso reais."
url: "https://wame.api.br/blog/tutorial-gerenciar-contatos-bloquear-whatsapp-api"
language: "pt-BR"
og:type: "article"
published_time: "2026-09-17"
modified_time: "2026-09-17"
author: "Raphael Serafim"
keywords: "gerenciar contatos whatsapp api, bloquear contato whatsapp api, desbloquear numero whatsapp api, listar contatos whatsapp api, perfil de contato whatsapp api"
reading_time: "8 min de leitura"
---

# Como gerenciar contatos pela API do WhatsApp

> Tutorial: como listar contatos, consultar perfil e bloquear/desbloquear pela API do WhatsApp — passo a passo com exemplos em cURL e casos de uso reais.

**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

```sh
curl https://server.wame.api.br/{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

```sh
curl https://server.wame.api.br/{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](/blog/whatsapp-calling-api-chamada-voz-video) para o próximo passo depois de confirmar quem é o contato).

### 3. Bloqueie um contato

```sh
curl -X PATCH "https://server.wame.api.br/{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

```sh
curl -X PATCH "https://server.wame.api.br/{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:

```js
async function bloquearPorAbuso(numero) {
  await fetch(`https://server.wame.api.br/${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.

```js
async function sincronizarContatos() {
  const resp = await fetch(`https://server.wame.api.br/${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:

```js
async function confirmarAntesDeAgir(numero) {
  const resp = await fetch(`https://server.wame.api.br/${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](/blog/automatizar-grupos-whatsapp-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:

| Mecanismo | O que resolve | Reversível? |
| --- | --- | --- |
| Bloquear contato | Impede qualquer mensagem daquele número chegar na instância | Sim, via desbloqueio |
| Opt-out de campanha | Remove o contato da lista de envio de disparo/marketing | Sim, com novo consentimento |

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](/blog/lista-contatos-optin-optout-whatsapp).

## 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](/blog/tutorial-gerenciar-chats-whatsapp-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](/blog/labels-api-whatsapp-organizar-conversas-sem-crm) complementa a gestão de contato com um sistema de etiquetas.

## Perguntas frequentes

### Dá para listar todos os contatos da instância pela API?

Sim, um GET no endpoint de contatos retorna a lista completa de contatos salvos na instância conectada, incluindo os dados básicos de cada um.

### O que aparece no perfil de um contato pela API?

Informações públicas do WhatsApp daquele número — nome de exibição, foto de perfil (quando visível) e status, dependendo da configuração de privacidade do contato.

### Bloquear um contato pela API tem o mesmo efeito de bloquear pelo app?

Sim. O contato bloqueado deixa de conseguir enviar mensagem para o número, exatamente como bloquear manualmente pelo aplicativo do WhatsApp.

### Quando faz sentido automatizar o bloqueio de contato?

Em cenários de abuso repetido — spam recebido, tentativa de golpe, comportamento que viola a política de uso — onde esperar uma ação manual atrasaria a proteção do número ou da equipe de atendimento.

### Bloquear contato pela API afeta o Quality Rating do meu número?

Não diretamente — Quality Rating reflete como o SEU número se comporta ao enviar, não quem você bloqueia. Mas bloquear quem denuncia mensagem indevida sua não resolve a causa; o que protege a reputação é corrigir o que gerou a denúncia.