--- title: "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://api-wa.me/blog/tutorial-gerenciar-contatos-bloquear-whatsapp-api" language: "pt-BR" og:type: "article" og:site_name: "WAME API" --- [Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/Como gerenciar contatos pela API do WhatsApp Raphael Serafim· Publicado em 17 de setembro de 2026· 8 min de leitura Compartilhar # 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. Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/tutorial-gerenciar-contatos-bloquear-whatsapp-api.md) **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 Copiar ``` 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 sh Copiar ``` 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](https://api-wa.me/blog/whatsapp-calling-api-chamada-voz-video) para o próximo passo depois de confirmar quem é o contato). ### 3\. Bloqueie um contato sh Copiar ``` 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 sh Copiar ``` 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: javascript Copiar ``` 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. javascript Copiar ``` 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: javascript Copiar ``` 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](https://api-wa.me/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](https://api-wa.me/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](https://api-wa.me/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](https://api-wa.me/blog/labels-api-whatsapp-organizar-conversas-sem-crm) complementa a gestão de contato com um sistema de etiquetas. ### Pronto para automatizar seu WhatsApp? Crie sua conta gratuita e comece a enviar mensagens pela API em minutos. [Começar grátis](https://portal.api-wa.me/sign-up) ## 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. ## Continue lendo [### Coexistência e a nova cobrança do WhatsApp: o que muda para quem atende pelo celular e pela API Quem usa Coexistência (API oficial + celular) sente a nova cobrança de agosto e outubro de 2026 de um jeito específico. Veja o que é cobrado e o que continua grátis.](https://api-wa.me/blog/coexistencia-nova-cobranca-whatsapp-2026)[### Como simular o custo da nova cobrança do WhatsApp antes de outubro de 2026 Passo a passo para medir, via webhook e API de analytics da Meta, quantas mensagens de serviço e de Business Agent seu número gera hoje — antes da cobrança começar.](https://api-wa.me/blog/simular-custo-mensagem-servico-whatsapp-2026)[### Automatizar grupos de WhatsApp pela API: guia completo Como automatizar grupos de WhatsApp pela API: criar, adicionar participante, moderar entrada e enviar aviso automático, com exemplos práticos em cURL.](https://api-wa.me/blog/automatizar-grupos-whatsapp-api) [Voltar ao blog](https://api-wa.me/blog) ## Structured data ```json { "@context": "https://schema.org", "@type": "WebSite", "name": "WAME API", "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram e Messenger", "url": "https://api-wa.me", "inLanguage": "pt-BR", "publisher": { "@id": "https://api-wa.me/#organization", "@type": "Organization", "name": "WAME API", "url": "https://api-wa.me" } } { "@context": "https://schema.org", "@type": "Organization", "@id": "https://api-wa.me/#organization", "name": "WAME API", "alternateName": [ "WAME", "Wame API", "wame.api.br", "api-wa.me" ], "url": "https://api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/web-app-manifest-512x512.png", "width": 512, "height": 512 }, "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.", "identifier": { "@type": "PropertyValue", "propertyID": "INPI-BR", "name": "Pedido de registro de marca (INPI, classe NCL 42)", "value": "944724159" }, "foundingDate": "2017", "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram e Messenger numa instância só. Desde 2017.", "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.", "knowsAbout": [ "WhatsApp Cloud API oficial (Meta)", "API oficial de Instagram (Direct)", "API oficial de Messenger", "API multicanal Meta", "Meta Business Partner", "WhatsApp API", "API não oficial de WhatsApp", "automação de WhatsApp", "números virtuais", "webhooks" ], "sameAs": [ "https://github.com/wame-api", "https://www.linkedin.com/company/wameapi", "https://www.instagram.com/wame.api/", "https://www.youtube.com/@wameapi" ], "contactPoint": { "@type": "ContactPoint", "contactType": "customer support", "url": "https://api-wa.me/contact", "availableLanguage": [ "Portuguese" ] } } { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "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.", "image": "https://api-wa.me/blog/tutorial-gerenciar-contatos-bloquear-whatsapp-api/opengraph-image", "datePublished": "2026-09-17", "dateModified": "2026-09-17", "author": { "@type": "Person", "name": "Raphael Serafim", "url": "https://github.com/raphaelvserafim", "sameAs": [ "https://github.com/raphaelvserafim" ] }, "publisher": { "@type": "Organization", "name": "api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/screenshot.png" } }, "mainEntityOfPage": { "@type": "WebPage", "@id": "https://api-wa.me/blog/tutorial-gerenciar-contatos-bloquear-whatsapp-api" }, "keywords": "gerenciar contatos whatsapp api, bloquear contato whatsapp api, desbloquear numero whatsapp api, listar contatos whatsapp api, perfil de contato whatsapp api", "inLanguage": "pt-BR" } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://api-wa.me" }, { "@type": "ListItem", "position": 2, "name": "Blog da API do WhatsApp", "item": "https://api-wa.me/blog" }, { "@type": "ListItem", "position": 3, "name": "Como gerenciar contatos pela API do WhatsApp", "item": "https://api-wa.me/blog/tutorial-gerenciar-contatos-bloquear-whatsapp-api" } ] } { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "Dá para listar todos os contatos da instância pela API?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "O que aparece no perfil de um contato pela API?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Bloquear um contato pela API tem o mesmo efeito de bloquear pelo app?", "acceptedAnswer": { "@type": "Answer", "text": "Sim. O contato bloqueado deixa de conseguir enviar mensagem para o número, exatamente como bloquear manualmente pelo aplicativo do WhatsApp." } }, { "@type": "Question", "name": "Quando faz sentido automatizar o bloqueio de contato?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Bloquear contato pela API afeta o Quality Rating do meu número?", "acceptedAnswer": { "@type": "Answer", "text": "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." } } ] } ```