Verificação de números no WhatsApp
Descubra pela API se um número tem WhatsApp antes de enviar: até 100 números por chamada, com o endereço registrado de cada um, nono dígito incluso.
Atualizado em
Nem todo telefone da sua base tem WhatsApp. Um cliente digitou o número errado no cadastro, trocou de linha, ou usa o WhatsApp em outro número. Enviar para esses contatos gasta tempo da fila e deixa o seu sistema esperando uma resposta que nunca vem. Com a verificação de números da apiwpp, você pergunta ao WhatsApp, antes de enviar, quais números estão registrados, até 100 de uma vez.
Como verificar
A verificação é feita por uma conexão, ou seja, por um dos seus números conectados, que precisa estar com o status open. Chame POST /connections/{id}/contacts/check com a lista de telefones em phones, só com dígitos, com o código do país e o DDD:
curl -s -X POST "https://api.apiwpp.com/connections/$CONNECTION_ID/contacts/check" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"phones": ["5511988887777", "5521977776666", "5531912345678"]}'
A resposta traz um resultado para cada número:
{
"results": [
{ "phone": "5511988887777", "exists": true, "jid": "[email protected]" },
{ "phone": "5521977776666", "exists": true, "jid": "[email protected]" },
{ "phone": "5531912345678", "exists": false }
]
}
exists diz se o número está no WhatsApp e jid é o endereço em que ele está registrado. Cada chamada aceita até 100 números; com mais, a resposta é 400, e basta dividir a lista em blocos. A chave de API precisa do escopo messages:send, porque a consulta é feita pelo número, como um envio.
Evite envios que falham
Quando você envia para um número que não está no WhatsApp, o envio falha na hora, sem novas tentativas. Se o envio tinha um clientRef, o seu webhook recebe message.send_failed com reason: not_on_whatsapp:
{
"type": "message.send_failed",
"data": {
"clientRef": "boas-vindas-8812",
"jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
"messageId": null,
"to": "5531912345678",
"reason": "not_on_whatsapp",
"attempts": 1
}
}
O envio não quebra nada, mas é melhor saber disso antes. No cadastro, você pode avisar o cliente que o número não tem WhatsApp enquanto ele ainda está na tela. Numa lista de lembretes do dia seguinte, você separa quem precisa de outro canal, como e-mail ou SMS, em vez de descobrir só depois do horário.
O nono dígito resolvido
Contas antigas de WhatsApp foram registradas antes do nono dígito dos celulares brasileiros. Nesses casos, o número que o cliente conhece tem o 9, mas o endereço no WhatsApp não tem. Quem monta o endereço na mão, acrescentando @s.whatsapp.net ao telefone, envia para um endereço que não existe.
A apiwpp pergunta ao WhatsApp em qual endereço (JID) cada número está registrado. No exemplo acima, 5521977776666 foi encontrado como [email protected], sem o 9. A API nunca inclui nem remove o nono dígito por conta própria: ela usa o que o WhatsApp responde.
Você não precisa chamar a verificação antes de cada envio para isso funcionar. O POST /connections/{id}/send faz a mesma consulta antes de enviar, então o campo to com o número completo, com o 9, chega também às contas antigas. A verificação serve para saber o resultado antes, em lote. O guia sobre o nono dígito explica o problema em detalhe, e o glossário resume o que é o nono dígito.
Quando usar
No cadastro. Ao receber um telefone num formulário, verifique o número e mostre o resultado na hora: "este número não tem WhatsApp, confira ou informe outro". Isso evita que o cliente fique sem as confirmações que esperava.
Na limpeza da base. Antes de migrar uma base de clientes para o WhatsApp, passe a lista pela verificação em blocos de 100, guarde o jid dos números encontrados e marque os que não existem. Faça isso com calma, não tudo de uma vez, porque cada consulta é feita pelo seu número.
Antes de uma sequência de envios. Para lembretes e avisos que saem todo dia, verificar os números novos da lista evita ocupar a fila com envios que falhariam.
A verificação não diz se a pessoa quer receber a mensagem. Ela confirma só que o número está no WhatsApp. Continue enviando apenas para quem é seu cliente ou pediu para receber, e respeite o ritmo da fila e o limite de destinatários novos por dia.
Números sem telefone: o LID
Em alguns eventos recebidos, o WhatsApp identifica o remetente por um LID, um identificador que esconde o telefone, e o campo phone chega vazio. Quando a apiwpp descobre o telefone desse contato, o seu webhook recebe contact.resolved, com o LID e o telefone, e você pode juntar os dois registros no seu sistema. O campo to do envio também aceita um JID, inclusive um @lid, usado como veio.
Perguntas frequentes
Quantos números posso verificar de uma vez?
Até 100 por chamada. Para listas maiores, divida em blocos de 100 e faça as chamadas em sequência, com calma, porque cada consulta é feita pelo seu número conectado.
Preciso verificar o número antes de cada envio?
Não. O envio já pergunta ao WhatsApp em qual endereço o número está registrado e falha na hora com notonwhatsapp se ele não existir. A verificação é útil para saber disso antes, no cadastro ou numa lista.
A verificação corrige o nono dígito?
Ela devolve o endereço (JID) em que o WhatsApp registrou o número, com ou sem o 9. A apiwpp nunca inclui nem remove o dígito por conta própria; ela usa a resposta do WhatsApp.
A conexão precisa estar ativa para verificar?
Sim. A consulta é feita pelo número conectado, que precisa estar com o status open. Com o número desconectado, a resposta é 400 com o status atual da conexão.
Outros recursos
Todos: Recursos →POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.
Cada número conectado tem uma fila que envia no ritmo de uma pessoa: limites por minuto, hora e dia, intervalo aleatório entre envios e um teto de destinatários novos por dia. Mensagens ilimitadas dentro desses limites.
O clientRef é o seu identificador de um envio. Repetir a requisição com o mesmo valor devolve o job original com duplicate: true, sem enfileirar outra mensagem, e o clientRef volta nos eventos de entrega e de falha.