API de Verificação do WhatsApp: Verificando o registro a partir do seu backend

Como as equipes de backend chamam uma API de verificação do WhatsApp, escolhem entre as verificações de registro, foto de perfil e conta comercial, e lidam com resultados indeterminados.

Uma API de verificação do WhatsApp recebe um número de telefone do seu servidor e retorna, na mesma resposta, se uma conta do WhatsApp estava registrada naquele número no momento da verificação. No WA Lookup, um número é enviado para POST /api/v1/check com a chave no cabeçalho X-API-Key e um service_type que seleciona a verificação de registro, foto de perfil ou conta comercial, enquanto o POST /api/v1/batch-check aceita até 100 números em uma única requisição síncrona. Uma verificação que não pode ser decidida retorna um código de negócio diferente de zero, que o código do backend deve tratar como "tente novamente mais tarde" em vez de uma resposta de não registrado.

O que uma API de verificação do WhatsApp oferece a um backend

Os resultados de busca para esta consulta são, em sua maioria, listagens de mercado e wrappers de API que mostram um parâmetro de telefone e uma resposta verdadeiro ou falso. Vários deles executam verificações por meio de uma sessão conectada do WhatsApp, portanto, a API para de responder quando esse telefone fica offline. Poucos explicam o que a resposta significa para o código que a consome ou como lidar com os casos em que nenhuma resposta é possível.

Para o trabalho de backend, o modelo mental útil é simples. Uma API de verificação do WhatsApp responde a uma pergunta por número: uma conta do WhatsApp estava registrada neste número quando a verificação foi executada? Esse é um sinal de presença de conta para uma plataforma. É uma boa entrada para:

• decidir se vale a pena tentar o WhatsApp para um contato antes de outro canal;
• limpar um campo de telefone em um CRM ou banco de dados de leads;
• adicionar contexto a uma fila de revisão de inscrição ou integração.

Não é uma declaração sobre quem detém o número ou se a pessoa concordou em ser contatada. Mantenha seus registros de consentimento e histórico de contato como entradas separadas e armazene a data de cada verificação para que o valor possa ser atualizado posteriormente.

Como chamar a API de verificação do WhatsApp para um único número

A chamada de número único é uma requisição HTTPS com uma resposta. Não há trabalho a ser criado, nada a ser consultado e nenhuma URL de retorno de chamada a ser exposta.

1. Normalize para E.164. Envie o número com um sinal de mais, o código do país e o número nacional, seguindo o plano de numeração ITU-T E.164. Remova espaços, colchetes e prefixos troncais nacionais. Um número móvel alemão escrito localmente como 0151 2345 6789 torna-se +4915123456789. A biblioteca libphonenumber do Google analisa a entrada bruta com uma região padrão e é mais segura do que regras de string escritas manualmente.
2. Escolha a verificação. Defina service_type como ws, ws_avatar ou ws_business dependendo da decisão que o resultado irá direcionar.
3. Autentique a partir do servidor. Envie a chave no cabeçalho X-API-Key. Carregue-a de um armazenamento de segredos ou configuração de ambiente e nunca a coloque em código de navegador, pacote de aplicativo móvel ou repositório público.
4. Envie POST /api/v1/check. O resultado para esse número chega na resposta da mesma requisição.
5. Ramifique com base no resultado. Um resultado concluído traz a resposta para a verificação selecionada. Um código de negócio diferente de zero significa que a verificação não pôde ser decidida no momento.

Construa o corpo da requisição e a análise da resposta a partir da documentação atual da API do WA Lookup. Payloads de exemplos de outros provedores diferem, e copiá-los é uma fonte comum de erros de integração.

Escolhendo o tipo de verificação: ws, ws_avatar ou ws_business

O valor de service_type decide qual sinal retorna. Escolha a verificação mais restrita que responde à pergunta que seu código está fazendo, pois cada verificação concluída é cobrada, independentemente de a resposta ser registrado ou não registrado.

ws

A verificação de registro. Ela informa ao backend se o número enviado tinha uma conta do WhatsApp registrada no momento da verificação. Este é o padrão para decisões de canal, limpeza de listas e revisão de inscrições.

ws_avatar

A verificação de foto de perfil. Além do registro, ela informa se uma foto de perfil está disponível e, quando houver, um link para ela. O link pode ser uma string vazia. Use-o para enriquecimento de registros de contato ou para dar a um revisor humano mais contexto. Uma foto ausente não diz nada sobre se o número está registrado.

ws_business

A verificação de conta comercial. Além do registro, ela informa se a conta é uma conta WhatsApp Business, o tipo de conta criado com o WhatsApp Business app ou plataforma de negócios. As equipes de vendas a utilizam para separar contas comerciais de contas padrão. Ela descreve apenas o tipo de conta e não é uma verificação de uma empresa legal.

Verificando até 100 números com o endpoint de verificação em lote

Quando um backend já possui um grupo de números, como uma importação noturna ou um envio de formulário com vários contatos, o POST /api/v1/batch-check envia até 100 números em uma única requisição síncrona. O lote inteiro retorna na resposta a essa requisição, ou a requisição falha como um todo.

Esse comportamento molda o código do cliente:

• Divida listas maiores. Separe a entrada em grupos de 100 ou menos e envie-os um após o outro ou com um número pequeno e controlado em trânsito.
• Trate uma requisição falha como uma unidade. Se a requisição do lote falhar, tente novamente aquele grupo; não marque seus números com nenhum resultado.
• Ainda leia os resultados por número. Dentro de um lote bem-sucedido, cada número tem seu próprio resultado concluído ou pendente, portanto, a lógica de ramificação do fluxo de número único se aplica a cada entrada.
• Desduplique primeiro. Normalizar antes de dividir em grupos geralmente revela duplicatas escritas em diferentes formatos locais; verificar cada número uma vez mantém os gastos previsíveis.

O endpoint de lote ainda é um fluxo de mesma resposta. É a ferramenta certa para dezenas ou algumas centenas de números manipulados pelo código do aplicativo, não para um arquivo com uma lista muito grande.

Lidando com verificações pendentes e erros de requisição

O erro de integração mais caro é escrever "não registrado" em um banco de dados quando a verificação nunca chegou a uma decisão. Um resultado concluído de não registrado é uma resposta real. Um código de negócio diferente de zero não é uma resposta.

Um padrão de ramificação prático:

Use backoff exponencial para novas tentativas e limite o número de tentativas, para que um problema temporário não se transforme em uma explosão de chamadas repetidas. Mantenha os números pendentes em um estado separado, como "aguardando nova verificação", o que permite que os relatórios os distingam dos resultados decididos.

Executando a integração em produção

Alguns hábitos operacionais tornam uma integração de verificação mais fácil de manter:

• Respeite os controles documentados. A documentação atual da API descreve controles de concorrência e tempo limite por usuário. Dimensione o número de requisições em trânsito para esses controles e leia a documentação novamente ao escalar, em vez de assumir uma permissão fixa por minuto.
• Monitore o saldo da conta. Um saldo de conta cobre o painel, a API REST e o servidor MCP, portanto, um grande trabalho de API e verificações manuais no painel consomem o mesmo saldo. Verifique o saldo no painel antes de uma execução grande.
• Registre sem vazar. Registre os resultados das requisições e códigos de erro, mas oculte números de telefone nos logs gerais do aplicativo e nunca registre a chave da API.
• Rotacione as chaves. O painel gerencia as chaves de API; rotacione uma chave se ela puder ter sido exposta e atualize o armazenamento de segredos em uma única etapa.
• Registre o contexto. Armazene qual verificação foi executada e quando. Um resultado de meses atrás descreve o número naquela época, não hoje.

Os Termos de Serviço do WhatsApp restringem o acesso automatizado ou não autorizado aos seus serviços, o que é uma das razões pelas quais as equipes abandonam scripts que conduzem uma sessão pessoal e migram para uma API hospedada com sua própria chave.

Quando uma tarefa de arquivo é mais adequada que a API

Para uma lista muito grande, uma tarefa em lote assíncrona é a melhor opção: faça o upload de um arquivo TXT ou CSV com um número por linha, aguarde o processamento e, em seguida, baixe um result.csv. As tarefas em lote usam POST /api/v1/bulk-tasks para enviar e GET /api/v1/bulk-tasks/{id} para acompanhar o progresso, e os limites por produto se aplicam conforme descrito na documentação da API. O arquivo deve conter números essencialmente de um país, e os serviços em lote não cobrem números da China continental, Hong Kong ou Macau. O saldo para tarefas em lote é reservado no envio, com a parte não utilizada retornada após o processamento.

Para a maioria dos recursos de backend que reagem a uma ação do usuário ou a uma pequena importação, as chamadas síncronas de número único e de lote permanecem a escolha mais simples.

FAQ

Como as equipes podem testar uma API de verificação do WhatsApp antes de integrá-la à produção?

Comece com alguns números cujo resultado esperado a equipe já conheça, como telefones da empresa, e chame o endpoint de número único a partir de um ambiente de teste. Contas novas elegíveis recebem automaticamente 100 verificações gratuitas uma vez após o registro, o que geralmente é suficiente para exercitar os caminhos de registrado, não registrado e nova tentativa no código do cliente.

O que um backend deve fazer quando um número retorna como pendente?

Deixe o campo de resultado vazio, registre o código de negócio e a hora, e coloque o número em uma fila de nova tentativa com backoff. Escrever um valor de não registrado para uma verificação pendente corrompe os dados da lista e leva a decisões de canal erradas posteriormente.

O endpoint de verificação em lote funciona de forma diferente de um upload de arquivo?

Sim. O endpoint de verificação em lote retorna até 100 resultados na resposta da mesma requisição. Um upload de arquivo cria uma tarefa em lote assíncrona que é processada em segundo plano, após o que um result.csv é baixado.

Qual tipo de verificação uma integração de CRM deve usar por padrão?

A verificação de registro, ws, cobre a maioria das decisões de canal e qualidade de dados. Adicione ws_avatar ou ws_business apenas quando um campo no CRM realmente usar a disponibilidade de foto de perfil ou o tipo de conta, já que cada verificação concluída é cobrada.

Saiba mais

Escolha as informações do produto que se encaixam na próxima etapa do seu fluxo de trabalho.

• Ver a documentação do produto →
• Falar com a equipe →