Verificar números
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.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador da conexão (o número) que faz a consulta.
Corpo da requisição
phonesstring[]obrigatórioOs 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.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | Um 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. |
| 400 | FST_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. |
| 400 | phones 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. |
| 401 | Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}. |
| 402 | subscription_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. |
| 403 | A chave não tem o escopo messages:send; a mensagem cita o escopo (This credential lacks the messages:send scope). |
| 404 | A 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"}). |
| 429 | Requisiçõ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 |
| 500 | O WhatsApp não respondeu a uma das consultas, e a requisição inteira falhou (Failed to check contacts). Nada muda: repita depois. |
| 501 | unsupported_by_providerO provedor da conexão não faz esta consulta. O corpo é {"error": "unsupported_by_provider"}. |
| 503 | A 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