Pular para o conteúdo

Verificar números

POST/connections/{id}/contacts/check

Pergunta ao WhatsApp, a partir do número da conexão, se cada telefone da lista tem uma conta no WhatsApp. Verifica até 100 números por requisição e responde um resultado por número, na mesma ordem do pedido. Escopo necessário: messages:send.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número) que faz a consulta.

Corpo da requisição

phonesstring[]obrigatório

Os telefones a verificar, com código do país e DDD (por exemplo, 5511988887777). Só os dígitos de cada item são lidos, então +55 (11) 98888-7777 também vale. De 1 a 100 itens.

até 100 itens

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200Um item em results por telefone, na ordem do pedido: phone (o valor exatamente como foi enviado), exists (true quando o número tem conta no WhatsApp) e jid (o endereço em que a conta está registrada; só vem quando exists é true). Use esse jid como to para enviar ao endereço confirmado.
400FST_ERR_VALIDATIONA requisição não segue o schema: o id do caminho não é um UUID, ou falta phones, ou ele não é uma lista, ou tem mais de 100 itens. message diz o que está errado.
400phones veio vazio ({"error": "phones array is required"}), ou a conexão não está open (Connection not ready (status: …)): o número precisa estar pareado e conectado.
401Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}.
402subscription_inactiveA organização não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Regularize o pagamento no painel para voltar a usar o número.
403A chave não tem o escopo messages:send; a mensagem cita o escopo (This credential lacks the messages:send scope).
404A conexão não existe ou não é de quem chama: o recurso de outra pessoa responde exatamente como um que não existe ({"error": "Connection not found"}).
429Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After
500O WhatsApp não respondeu a uma das consultas, e a requisição inteira falhou (Failed to check contacts). Nada muda: repita depois.
501unsupported_by_providerO provedor da conexão não faz esta consulta. O corpo é {"error": "unsupported_by_provider"}.
503A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere os segundos de Retry-After e tente de novo.Cabeçalho: Retry-After

Detalhes

Cada número é consultado sozinho (até 10 ao mesmo tempo), porque o WhatsApp responde com o JID em que a conta está registrada, e ele pode não ter os mesmos dígitos que você enviou: uma conta brasileira registrada antes do nono dígito existe como [email protected], não como [email protected]. O gateway nunca põe nem tira o nono dígito por conta própria; jid traz o endereço que o WhatsApp respondeu.

É a mesma consulta que POST /connections/{id}/send faz antes de enviar para um número: um número que não está no WhatsApp falha na hora, sem novas tentativas. As respostas positivas ficam guardadas por 7 dias e são reaproveitadas pelos envios; as negativas não são guardadas, porque o número pode entrar no WhatsApp depois.

A consulta usa a sessão de WhatsApp do número, como um envio: por isso pede o escopo messages:send, a conexão open e a organização em dia. Ela não conta na cota de mensagens do plano. Se o WhatsApp não responder a uma das consultas, a requisição inteira falha com 500 ({"error": "Failed to check contacts"}); repita depois.

Guia: Enviar mensagens

Esta página ajudou? · Atualizado em 28 set 2026