Integrando o WA Lookup: higiene automatizada de dados do CRM e classificação de contas

Saiba como integrar a API síncrona do WA Lookup para verificar a presença de conta no WhatsApp, obter detalhes do avatar e classificar contas comerciais para a higiene de dados do CRM.

A API do WA Lookup permite que sistemas de CRM façam a verificação síncrona da presença de conta no WhatsApp. Ao enviar uma requisição POST ao endpoint /api/v1/check com um número de telefone no formato E.164, os desenvolvedores podem obter o status de registro, a disponibilidade do avatar ou a classificação de conta comercial na mesma resposta HTTP. Esses dados ajudam a manter a higiene do CRM ao identificar registros válidos vinculados ao WhatsApp, sem exigir processamento assíncrono, consulta periódica ou webhooks.

Entendendo a arquitetura da API do WA Lookup

Integrar sinais de presença de conta a um CRM exige uma arquitetura que suporte o roteamento imediato dos dados e a tomada de decisão. A API do WA Lookup foi projetada em torno de um único endpoint síncrono: POST /api/v1/check. Quando um sistema de CRM ou uma plataforma de operações de dados envia uma requisição, a API processa a verificação e entrega os resultados na mesma resposta HTTP. Essa arquitetura síncrona elimina o esforço de engenharia associado ao processamento assíncrono, como configurar webhooks, gerenciar URLs de callback ou implementar lógica de consulta periódica. Os desenvolvedores podem integrar a API diretamente a fluxos síncronos, como formulários de captação de leads ou pipelines de limpeza de dados em tempo real. Para uma verificação do WhatsApp concluída, o data retornado contém service_type, identifier e registered; ws_avatar também inclui avatar e avatar_url, enquanto ws_business inclui business. Campos internos de registro, transação, status e cobrança não são retornados.

Classificando os tipos de conta do WhatsApp

Para atender a diferentes requisitos de higiene de dados do CRM, a API em tempo real oferece três tipos de serviço distintos. Os três usam o mesmo endpoint síncrono, e o parâmetro service_type controla quais campos específicos são retornados na resposta e qual custo de saldo se aplica à transação.

Comparando os tipos de serviço

O WhatsApp Checker (ws) é o tipo de serviço básico. Ele é usado apenas para confirmar se um número de telefone enviado está registrado no WhatsApp, retornando somente o campo registered. Normalmente é usado para a limpeza básica de listas e para identificar quais contatos do CRM têm conta no WhatsApp. O WhatsApp Avatar Checker (ws_avatar) amplia a verificação básica com recursos de enriquecimento de perfil. Além do status de registro, ele retorna um booleano avatar que indica se há uma foto de perfil definida e uma string avatar_url. O campo de URL fica vazio quando não há URL disponível. Esse sinal pode ajudar as equipes a avaliar a completude do perfil de um contato. O WhatsApp Business Checker (ws_business) foi projetado para a segmentação de CRM B2B. Ele verifica o registro no WhatsApp e retorna um booleano business que indica se a conta usa o WhatsApp Business. Isso permite que gestores de operações de dados separem contas pessoais de contas comerciais em suas bases.

Implementação técnica e higiene de dados

Integrar a API a um CRM ou pipeline de dados exige seguir o contrato de requisição documentado. A API espera um payload JSON e cabeçalhos específicos para autenticar e processar a requisição com sucesso. O contrato de requisição documentado exige uma requisição POST para /api/v1/check. A requisição deve incluir dois cabeçalhos: X-API-Key, contendo sua chave de autenticação, e Content-Type: application/json. O corpo JSON deve conter exatamente dois campos:

1. service_type: um valor de string ws, ws_avatar ou ws_business.
2. identifier: o número de telefone a ser verificado.

É fundamental que todos os números de telefone enviados estejam formatados de acordo com o plano internacional de numeração telefônica E.164. Por exemplo, um número dos EUA deve ser enviado como +17253100591. Não usar o formato E.164 pode resultar em erros de interpretação ou verificações indeterminadas. Um corpo JSON padrão tem esta aparência: {"service_type": "ws_business", "identifier": "+17253100591"} Ao padronizar as entradas do CRM em E.164 e encaminhá-las por essa verificação síncrona, os desenvolvedores podem sinalizar automaticamente números inválidos, segmentar usuários comerciais e manter um alto padrão de higiene de dados. Como a resposta é imediata, essas verificações podem ser integradas diretamente aos formulários de entrada de dados, garantindo que apenas sinais de presença de conta verificados sejam gravados no banco de dados.

Relatórios do painel e gerenciamento da conta

O gerenciamento do uso da API e o monitoramento das operações de higiene de dados são feitos pelo painel da plataforma. O painel oferece ferramentas completas para que administradores de CRM e desenvolvedores acompanhem o desempenho da integração e gerenciem a autenticação. O painel oferece gerenciamento completo de chaves de API, permitindo que as equipes façam a rotação das chaves com segurança. Para supervisão operacional, ele dá visibilidade do saldo atual da conta, do histórico detalhado de verificações e de relatórios por produto. Os administradores podem revisar verificações recentes, monitorar o consumo de saldo e analisar a atividade da conta para entender como a API está sendo utilizada nos diferentes fluxos do CRM. Para uma verificação do WhatsApp concluída, o data retornado contém service_type, identifier e registered; ws_avatar também inclui avatar e avatar_url, enquanto ws_business inclui business. Campos internos de registro, transação, status e cobrança não são retornados.

Perguntas frequentes

A API do WA Lookup é síncrona ou assíncrona?

A API do WA Lookup é estritamente síncrona. Quando uma requisição é enviada ao endpoint POST /api/v1/check, os resultados são devolvidos na mesma resposta HTTP da requisição.

Esta API consegue verificar se um usuário está online no momento?

Não. Um resultado registrado informa os campos de status do WhatsApp disponíveis no momento da verificação. Ele funciona apenas como um sinal de presença de conta e não informa presença ao vivo, histórico de mensagens, consentimento do contato nem se o número pode ser contatado no momento.

Qual é a diferença entre os tipos de serviço ws, ws_avatar e ws_business?

Os três tipos de serviço usam o mesmo endpoint síncrono, mas retornam campos diferentes. O tipo de serviço ws confirma o registro básico no WhatsApp. O tipo de serviço ws_avatar retorna o status de registro junto com um booleano avatar e um campo de URL do avatar, que fica vazio quando não há URL disponível. O tipo de serviço ws_business retorna o status de registro e um booleano que indica se a conta usa o WhatsApp Business.