Como integrar a API do WA Lookup para enriquecer perfis do WhatsApp

Um guia técnico para desenvolvedores sobre como implementar consultas síncronas de perfil e avatar do WhatsApp com a API do WA Lookup.

A API do WA Lookup oferece uma interface REST síncrona que ajuda os desenvolvedores a automatizar o enriquecimento de perfis do WhatsApp. Ao enviar uma requisição POST para o endpoint /api/v1/check com um tipo de serviço específico — ws, ws_avatar ou ws_business — e um número de telefone no formato E.164, a API retorna sinais imediatos de presença da conta diretamente na resposta HTTP. Esses sinais incluem o status de registro, a disponibilidade de avatar, URLs de avatar e indicadores de conta Business, que podem servir de entrada para o roteamento no CRM, a segmentação de público e fluxos internos de apoio à decisão.

Introdução à API do WA Lookup

Ao integrar canais de comunicação aos fluxos de trabalho da empresa, as equipes técnicas precisam de sinais precisos de presença da conta para orientar sua lógica de roteamento e segmentação. O WA Lookup oferece verificações síncronas individuais e em pequenos lotes para registro no WhatsApp, disponibilidade de avatar e status de conta Business. O endpoint individual verifica um identificador, e o endpoint múltiplo síncrono aceita até 100 identificadores; ambos retornam os dados na mesma resposta HTTP. Essa arquitetura síncrona permite decisões imediatas, sem webhooks assíncronos, infraestrutura de polling ou filas de processamento em lote. É fundamental entender os limites desse sinal de presença da conta. Um resultado registrado informa os campos de status do WhatsApp disponíveis no momento exato da verificação. Ele não informa presença em tempo real, histórico de mensagens, consentimento do usuário nem se o número pode ser contatado no momento. Em vez disso, ele contribui para um fluxo de trabalho mais amplo, ajudando as equipes a revisar registros e priorizar o contato com base na presença na plataforma.

Entendendo os tipos de serviço

A API do WA Lookup reúne seus recursos em um único endpoint síncrono. Os desenvolvedores controlam quais sinais de perfil são obtidos — e qual custo é debitado do saldo — alterando o parâmetro service_type no corpo da requisição. A API oferece três tipos de serviço distintos:

• WhatsApp Checker (ws): é o tipo de serviço básico. Seu escopo se limita a confirmar se o número de telefone enviado está registrado no WhatsApp. Ele fornece um sinal básico de registro na plataforma.
• WhatsApp Avatar Checker (ws_avatar): este tipo de serviço amplia a verificação básica com o enriquecimento de perfil. Além de verificar o registro no WhatsApp, ele verifica a disponibilidade de avatar e retorna um campo avatar_url. O campo de URL fica vazio quando não há URL disponível.
• WhatsApp Business Checker (ws_business): este tipo de serviço foi pensado para fluxos B2B. Ele verifica o registro padrão no WhatsApp e, além disso, determina se a conta usa o WhatsApp Business, fornecendo um sinal específico de perfil comercial.

Ao escolher o tipo de serviço adequado, os gerentes de produto técnicos podem ajustar a saída da API aos requisitos exatos do fluxo de trabalho, garantindo que solicitem e consumam apenas os dados necessários para o caso de uso específico.

Implementação técnica

A integração da API do WA Lookup exige seguir um contrato de requisição JSON rigoroso e regras de formatação. Todas as interações acontecem pelo endpoint POST /api/v1/check. Para autenticar e formatar a requisição corretamente, os desenvolvedores devem incluir cabeçalhos específicos: o cabeçalho X-API-Key, com a chave de API ativa, e o cabeçalho Content-Type: application/json. O corpo JSON da requisição deve conter exatamente dois campos:

1. service_type: uma string com o valor "ws", "ws_avatar" ou "ws_business".
2. identifier: o número de telefone de destino, enviado estritamente no formato E.164.

O formato E.164 é um plano internacional de numeração telefônica que garante que os números de telefone sejam inequívocos no mundo todo. Um número no formato E.164 deve começar com o sinal de mais (+), seguido imediatamente do código do país e do número do assinante, sem espaços, hifens ou parênteses (por exemplo, +17253100591). Não usar o formato E.164 fará com que a verificação não seja concluída. Como a API é totalmente síncrona, a conexão HTTP permanece aberta enquanto a verificação é realizada, e os resultados chegam na resposta HTTP imediata.

Interpretando as respostas da API

A API do WA Lookup retorna um conjunto previsível de campos em toda resposta de verificação, com campos adicionais conforme o service_type selecionado. Em uma verificação de 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. Quando o service_type é ws, o resultado inclui apenas o campo registered, junto com os valores service_type e identifier devolvidos como foram enviados. Quando o service_type é ws_avatar, o esquema da resposta passa a incluir um campo avatar (um booleano que indica se há um avatar definido) e um campo avatar_url. O avatar_url é uma string vazia quando não há URL disponível. Quando o service_type é ws_business, o esquema da resposta acrescenta um campo business, um booleano que indica se o número registrado está associado a uma conta do WhatsApp Business.

Painel e gestão de uso

A gestão do uso da API e o acompanhamento das entradas do fluxo de trabalho são feitos pelo painel da plataforma. O painel oferece suporte completo à gestão de chaves de API, permitindo que os desenvolvedores gerem e renovem com segurança as chaves exigidas no cabeçalho X-API-Key. Para a supervisão operacional, o painel inclui recursos para acompanhar o saldo, revisar o histórico de verificações e acessar relatórios por produto. As equipes técnicas podem monitorar verificações recentes, analisar o consumo do saldo e ver a atividade da conta para entender seus padrões de uso e otimizar a integração. Revise o saldo e o histórico de verificações no painel; consulte a página de preços e a documentação da API para conhecer as regras de cobrança atuais.

Perguntas frequentes

A API do WA Lookup é síncrona?

Sim. Os endpoints em tempo real são síncronos: os resultados são retornados na mesma resposta HTTP da requisição inicial. O endpoint de número individual verifica um identificador, e o endpoint múltiplo síncrono aceita até 100 identificadores sem jobs, callbacks ou polling. Listas maiores são tratadas por um produto de verificação em massa assíncrono e separado, no qual você envia um arquivo e baixa o resultado depois.

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

O tipo de serviço ws retorna apenas o sinal básico de registro no WhatsApp. O tipo de serviço ws_avatar retorna o sinal de registro e, além disso, verifica a disponibilidade de avatar, retornando uma string avatar_url que fica vazia quando não há URL disponível.

Qual formato os números de telefone devem seguir?

Todos os números de telefone enviados à API devem estar formatados de acordo com o padrão E.164. Isso exige o sinal de mais (+) seguido do código do país e do número do assinante, sem espaços nem caracteres especiais.