WA Lookup
Um número de telefone passando por um pipeline síncrono de verificação de registro até um resultado concluído
Uma requisição leva um número normalizado pela validação e devolve um resultado de registro.

O que “tempo real” significa para este produto

Tempo real significa que a decisão de registro é devolvida na mesma requisição HTTP, e não por meio de um job em segundo plano, webhook ou exportação posterior.

O chamador envia um número de telefone normalizado e aguarda a resposta. Quando a verificação é concluída, data.registered informa se esse número estava registrado no WhatsApp no momento da requisição. O chamador pode usar o resultado imediatamente, sem consultar outro endpoint.

Esse é um contrato de produto restrito. O WA Lookup verifica o status de registro; ele não identifica a pessoa por trás do número, não monitora a atividade da conta e não opera um serviço de mensagens. Deixar esse escopo explícito facilita o uso correto do campo retornado.

Dados retornados Significado Ação recomendada
code=0, registered=true A verificação concluída indicou registrado Use o resultado booleano retornado por esta requisição
code=0, registered=false A verificação concluída indicou não registrado Use false como resultado concluído
Código de negócio diferente de zero O serviço não devolveu decisão de registro Não invente um booleano; trate o erro ou tente novamente conforme a documentação da API

Por que verificações síncronas são úteis

Um resultado síncrono é útil quando a próxima etapa do software depende de uma resposta de registro atual. A aplicação não precisa criar um job, persistir um token de consulta ou aguardar um callback antes de classificar o número.

Integrações típicas incluem um formulário interno que verifica um número, uma ferramenta de suporte que confere um registro sob demanda ou um worker de backend. Para listas pequenas, o endpoint síncrono em lote aceita até 100 identificadores em E.164 e devolve o lote concluído na própria resposta da requisição. Ainda assim, os clientes devem controlar a própria concorrência.

O principal benefício arquitetural é o determinismo: uma resposta concluída contém uma única decisão booleana de registro. Erros da API e verificações indeterminadas usam o envelope externo code, msg e data, em vez de acrescentar mais valores a registered.

O caminho da requisição, passo a passo

  1. Normalize o número de telefone — Converta um código de discagem do país bem conhecido e o número nacional para o formato E.164. Não tente adivinhar o contexto de país ausente.
  2. Envie uma verificação — Chame o endpoint de verificação autenticado com o número normalizado e service_type=ws.
  3. Leia o resultado concluído — Use data.registered quando code=0; deixe-o sem valor quando a API retornar um código de negócio diferente de zero.
  4. Armazene o horário da observação — O registro é um resultado pontual, então salve quando ele foi verificado.
  5. Trate os não resultados separadamente — Uma requisição inválida ou uma falha temporária exige correção ou nova tentativa, não um valor de registro false.

Modele o resultado sem perder o significado

Evite um campo genérico como valid. Ele não consegue distinguir uma entrada malformada de um número válido cuja verificação terminou como não registrado. Um registro pequeno e explícito é mais seguro:

Campo Finalidade
source_phone Preserva o valor fornecido pelo sistema de origem
e164_phone Armazena o número canônico enviado para verificação
outcome A classificação da sua aplicação: concluído, passível de nova tentativa ou requisição com falha
registered Armazena true ou false apenas para uma verificação concluída
checked_at Registra quando a observação pontual foi feita
service_type Registra qual contrato de produto gerou o resultado

Erros HTTP não são valores adicionais para esse registro. Se uma aplicação os registrar em log, deve armazenar o status HTTP retornado e o code da API separadamente das observações de registro.

Uma regra prática de integração

Só tome decisões com base em data.registered quando a resposta externa tiver code=0.

Essa única regra evita o erro de interpretação mais comum: tratar um timeout, uma requisição rejeitada ou um número malformado como se o WhatsApp tivesse informado que o número não está registrado. Se a decisão precisar estar atualizada em um momento posterior, faça uma nova verificação síncrona e salve-a como uma nova observação, em vez de alterar silenciosamente o carimbo de data/hora antigo.

Fontes