Como fazer uma consulta de registro no WhatsApp

Um guia prático para equipes de negócio e técnicas sobre como fazer verificações síncronas de registro no WhatsApp usando a plataforma WA Lookup, abrangendo fluxos de número único e em lote.

Uma consulta de registro no WhatsApp é uma verificação síncrona que confirma se um número de telefone específico está atualmente associado a uma conta do WhatsApp. Com a plataforma WA Lookup, as organizações podem obter sinais de presença de conta em tempo real para números individuais ou pequenos lotes. Essas verificações fornecem dados imediatos para orientar fluxos internos de revisão, ajudando as equipes a segmentar públicos e priorizar o contato com base no registro atual na plataforma.

Entendendo os sinais de registro no WhatsApp

Quando as organizações processam listas de contatos, um sinal de registro no WhatsApp fornece um indicador claro de presença de conta no momento exato da verificação. Esse sinal confirma que um número de telefone E.164 enviado está registrado na plataforma. A plataforma WA Lookup devolve esses dados de forma síncrona, permitindo que as equipes integrem o resultado diretamente aos seus fluxos operacionais. É importante delimitar corretamente esse sinal dentro dos processos de negócio. Um resultado de registro informa estritamente a presença de conta. Ao tratar o sinal como uma entrada entre outras verificações, as equipes podem organizar melhor suas estratégias de comunicação sem superestimar a alcançabilidade de um determinado contato.

Fazendo uma consulta de número único

As equipes podem verificar números de telefone individuais usando a API REST síncrona do WA Lookup. O contrato de requisição documentado exige o envio de uma requisição POST /api/v1/check. Essa requisição deve incluir um cabeçalho X-API-Key para autenticação e um payload JSON contendo o número de telefone E.164 de destino e um campo service_type. Como a arquitetura é totalmente síncrona, a API devolve o resultado concluído na própria resposta HTTP da requisição. O envelope externo da resposta de uma verificação concluída inclui code, msg e data. Se uma verificação não puder ser decidida, a API retorna um código de negócio diferente de zero em vez de um objeto de resultado concluído.

Verificação de registro padrão

Usar o tipo de serviço ws retorna o objeto de dados básico. Ele inclui o service_type, o identifier e um campo booleano registered que indica a presença da conta.

Verificação com enriquecimento de avatar

Selecionar o tipo de serviço ws_avatar executa a verificação de registro padrão e acrescenta os campos avatar e avatar_url à resposta. O avatar_url pode retornar como string vazia dependendo da configuração da conta.

Verificação de perfil comercial

O tipo de serviço ws_business verifica o registro padrão e acrescenta um campo booleano business para indicar se a conta usa o WhatsApp Business.

Processando consultas em lote

Para fluxos que exigem maior vazão, o WA Lookup oferece um endpoint síncrono em lote. As organizações podem enviar até 100 identificadores em uma única requisição. Esse recurso foi projetado para oferecer eficiência mantendo o mesmo modelo de resposta em tempo real da verificação de número único. O endpoint em lote processa os números E.164 enviados e devolve o conjunto inteiro de resultados em uma única resposta, ou falha como um todo. Isso elimina a necessidade de arquiteturas assíncronas complexas. As equipes não precisam implementar filas de envio de tarefas, mecanismos de consulta periódica ou webhooks de callback para obter seus dados. O design síncrono garante que os resultados do lote fiquem imediatamente disponíveis para roteamento ou segmentação posteriores.

Acessando os resultados pelo painel ou pela API

As organizações podem interagir com o WA Lookup por meio de um painel web SaaS ou de forma programática pela API REST. Os dois métodos de acesso compartilham a mesma semântica de resultados síncronos e o mesmo saldo da conta. O painel web oferece uma interface visual para gerenciar chaves de API, consultar o saldo da conta e analisar o histórico de verificações. As equipes podem acessar relatórios por produto, revisar verificações recentes, monitorar o consumo de saldo e acompanhar as tendências de uso dos últimos 7 dias. Para o acesso programático, a documentação da API descreve os controles de concorrência por usuário e de timeout. A cobrança funciona no modelo de pagamento por verificação, e verificações com falha ou indeterminadas são reembolsadas automaticamente.

Integração com clientes de IA compatíveis com MCP

Além do acesso padrão pela API REST, o WA Lookup oferece um servidor oficial do Model Context Protocol (MCP). Esse servidor pode ser acessado no caminho /mcp do site via Streamable HTTP e JSON-RPC. Ele permite que clientes de IA compatíveis com MCP, como Claude Code ou Claude Desktop, interajam diretamente com as ferramentas de verificação. A integração MCP usa a chave de API já existente do cliente e compartilha exatamente os mesmos produtos, saldo, limites de concorrência e cobrança da API REST. Ela expõe ferramentas específicas ao assistente de IA: listar os produtos disponíveis, verificar um único número E.164, verificar de forma síncrona um pequeno lote de até 100 números e consultar o saldo da conta. Assim como a API padrão, as chamadas MCP são síncronas e em tempo real, devolvendo sinais de presença de conta sem criar tarefas assíncronas nem arquivos para download.

Perguntas frequentes

O que significa um status 'registered'?

Um resultado registrado indica que o número de telefone E.164 enviado está associado a uma conta do WhatsApp no momento da verificação. Ele funciona como um sinal de presença de conta para orientar fluxos internos.

As organizações podem verificar vários números de uma vez?

Sim, o WA Lookup oferece um endpoint síncrono em lote que aceita até 100 identificadores em uma única requisição. O lote inteiro é processado e devolvido na mesma resposta HTTP.

Como as equipes podem obter créditos na conta para testes?

Contas novas podem entrar em contato com o suporte para receber 100 verificações gratuitas, que podem ser usadas para experimentar o serviço e avaliar a API síncrona ou os recursos do painel.

Existem limites de requisições por minuto na API?

A documentação pública da API descreve controles de concorrência por usuário e de timeout, e não um limite rígido de requisições por minuto. As equipes devem consultar a documentação atual da API para conhecer o comportamento aplicável e as diretrizes de concorrência.