Pular para o conteúdo principal
GET
Existência de Destinatário (Sem Instância)

Introdução

Este endpoint verifica se um número existe no WhatsApp sem exigir uma instância conectada. A consulta é atendida por uma infraestrutura dedicada da própria Zapster, com cache persistente, então não depende de você ter um número próprio ativo na plataforma. A resposta traz o ID do destinatário, se é uma conta comercial, o LID e a URL da foto de perfil.
Endpoint público. No momento, este endpoint pode ser usado sem autenticação. Por ser público, as requisições sem token ficam sujeitas a limites de uso gratuito, mais restritos e que podem mudar a qualquer momento. Com o token da sua conta, valem os limites da sua conta. Ao ultrapassar o limite, a resposta é 429 com o código rate_limited e o header Retry-After indica quando tentar de novo.
Diferente da Verificação de Número (que exige instance_id), este endpoint só retorna o campo name para contas comerciais (is_business: true), com o nome da empresa no WhatsApp. O nome de um contato pessoal só existe no histórico de conversa de uma instância específica, então ele nunca é retornado aqui.

Casos de Uso

  • Validação em formulários de cadastro: confirme que um número tem WhatsApp antes de salvá-lo, mesmo antes de ter qualquer instância conectada.
  • Limpeza de base de contatos: valide listas de telefones em lote (veja a versão em lote) sem consumir a cota de uma instância de envio.
  • Pré-venda e onboarding: use no seu fluxo de signup ou numa ferramenta pública para mostrar valor antes do cliente configurar uma instância.

Por que não precisa de instância?

A consulta é atendida por um pool de números dedicados da própria Zapster, reservado exclusivamente para esse tipo de verificação. As instâncias dos seus clientes nunca são usadas para checar números de terceiros. O resultado passa por um cache que reduz consultas repetidas ao mesmo número, o que também torna respostas para números já conhecidos praticamente instantâneas.

Formato do número

O recipient deve estar em formato internacional (E.164): código do país seguido do número, com o + inicial opcional. Ambos os formatos abaixo são aceitos:
Um número fora desse formato (por exemplo, sem código de país) retorna 400 com o código recipient_invalid_format.
Nono dígito no Brasil. Números de celular brasileiros podem ser informados com ou sem o nono dígito (5511999999999 ou 551199999999) — ambas as grafias resolvem para a mesma conta no WhatsApp, e a API aceita qualquer uma delas.

Pontos de Atenção

O campo profile_picture está sempre presente em um destinatário encontrado: é uma URL estável que aponta para o endpoint de Foto de Perfil do Destinatário. Ela não expira como uma URL assinada, então pode ser armazenada e usada diretamente em um <img src> — a cada acesso, a foto mais recente disponível é servida. Quando o contato mantém a foto de perfil privada ou não possui nenhuma foto atribuída, o endpoint responde com um avatar genérico (placeholder), configurável pelo parâmetro placeholder.
Este endpoint tem um limite de requisições próprio, diferente do limite padrão da API, e os valores podem mudar a qualquer momento. Ao ultrapassar o limite, a resposta é 429 com o código rate_limited e os headers descritos na seção de erros da resposta abaixo.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Parâmetros de caminho

recipient
string
obrigatório

Número do destinatário em formato internacional (E.164), com ou sem o + inicial.

Resposta

Success

id
string
obrigatório

ID ou número do destinatário.

is_business
boolean
obrigatório

Define se o recipient informado é um perfil do tipo business ou normal.

profile_picture
string<uri>
obrigatório

Foto de perfil do destinatário. Sempre presente — é uma URL estável que aponta para o endpoint de foto de perfil (GET /wa/recipients/{recipient}/pp), então pode ser usada diretamente em um <img src> e armazenada como referência. Quando o número não tem foto disponível, esse endpoint responde com um placeholder configurável.

Exemplo:

"https://api.zapsterapi.com/v1/wa/recipients/5511999999999/pp"

lid
string

Identificador LID do destinatário no WhatsApp.

name
string

Nome da conta comercial (WhatsApp Business), como aparece no WhatsApp. Presente apenas quando is_business é true e a conta tem um nome; contas pessoais nunca trazem esse campo.

Exemplo:

"Padaria Pão Quente"