Provado em aparelho real em 10/11/2026: a resolução do nono dígito no envio. Beta: pode mudar:
contact.checke o comportamento com@lid.
Resposta curta: no Brasil, uma conta de WhatsApp pode existir com o nono dígito (5547999999999, 13 dígitos) ou sem ele (554799999999, 12 dígitos), e o WhatsApp só aceita a forma em que a conta foi criada. A API tenta as duas, lembra a que funcionou e a verificação de números não decide o 9. Guarde a forma que o envio usou, não só a que foi digitada.
Este guia explica por que isso acontece, o que a API faz sozinha, o que é o @lid e como o seu sistema deve guardar telefones.
Por que o mesmo telefone tem duas formas?
Os celulares brasileiros tinham 8 dígitos depois do DDD, e o nono dígito foi acrescentado região por região a partir de 2012. Contas de WhatsApp antigas ficaram registradas na forma curta. O resultado é que duas pessoas com o mesmo número no celular podem estar, para o WhatsApp, em formas diferentes: uma em 55 47 9 9999 9999, outra em 55 47 9999 9999.
No teste de 10/11/2026, uma conta pareada com o número digitado com o 9 ficou registrada sem ele. Enviar para a forma com o 9 falhou, e para a forma sem o 9 funcionou. Uma consulta simples de "este número existe?" respondeu "existe" para as duas formas, então ela sozinha não serve para decidir. É por isso que a API não confia em uma única verificação.
O que a API faz sozinha?
Em cada envio para um telefone brasileiro, a API faz o seguinte:
- Normaliza o destino (aceita
+55 (47) 99999-9999, só dígitos ou<dígitos>@s.whatsapp.net). - Tenta a forma com o nono dígito. Se o WhatsApp recusar por "o destinatário não está no WhatsApp", nada foi enviado e a API tenta a forma sem o 9 (e o contrário, para um número de 12 dígitos).
- Lembra a forma que funcionou para aquele destino, até 2.000 números por instância, e usa a mesma nas próximas vezes.
- Se nenhuma funcionar, responde 422
number_not_on_whatsapp.
Em grupo (@g.us) não há segunda tentativa: o identificador do grupo é o que o WhatsApp deu.
Como verificar antes de enviar?
POST /contacts/check devolve, para cada telefone, exists, o number e o jid:
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/contacts/check" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"numbers":["5547999999999"]}'
{ "ok": true, "data": { "results": [ { "input": "5547999999999", "exists": true, "number": "5547999999999", "jid": "[email protected]", "note": "br_9th_digit_unverified" } ] } }
Atenção: a consulta não distingue o nono dígito. Para número brasileiro, a resposta traz note: br_9th_digit_unverified, e o number volta como você mandou; o WhatsApp responde "existe" para as duas formas. Quem descobre a forma que funciona é o envio, que tenta as duas e lembra a certa. Por isso a verificação serve para saber se o telefone tem WhatsApp, e não para decidir o 9. O guia de contatos traz os limites diários dessa consulta. Exemplo real (10/11/2026): uma conta antiga, pareada com o número digitado com o 9, só aceitou mensagem na forma sem o 9. O envio para a forma com o 9 falhou, o envio sem o 9 funcionou, e a consulta disse "existe" para as duas. A pessoa continua vendo o mesmo telefone no celular dela.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisO que é o @lid?
O @lid é um identificador interno que o WhatsApp passou a usar no lugar do telefone em alguns contextos, para proteger o número de quem participa de grupos e de quem tem a privacidade do telefone ligada. Em vez de [email protected], a mensagem pode chegar associada a algo como 173074381074537@lid.
O que isso muda para você:
- O telefone nem sempre aparece. Nos avisos, o campo
frommostra os dígitos do telefone quando a ProxyBox consegue obtê-los; quando só existe o@lid,frompode vir nulo. Oname(o nome que a pessoa usa no WhatsApp) continua vindo. - Para responder, use a conversa. Em conversa individual, o identificador da conversa (
chat) serve para responder, mesmo sem telefone. Em grupo, use oiddo grupo. - Não tente adivinhar o telefone. Um
@lidnão é um telefone e não se converte em um. Se o seu fluxo precisa do telefone, peça para a pessoa informá-lo na conversa. - O
@lidnão deve ser guardado como se fosse telefone. Guarde-o numa coluna à parte, junto do nome, se precisar reconhecer a mesma pessoa depois.
[Recurso em beta: pode mudar.] O comportamento de from com @lid foi desenhado para nunca inventar um telefone: se ele não é conhecido, vem nulo.
O que o seu sistema deve fazer?
- Guarde só dígitos, com o código do país (
5547999999999). - Não faça a conta do nono dígito por conta própria. Deixe o envio resolver.
- Compare as duas formas ao procurar um cliente: um telefone pode chegar com 12 e estar na sua base com 13 dígitos. A lista de não perturbe da API já compara as duas formas.
- Use
Idempotency-Keynos envios. Como a API pode tentar duas formas, a chave evita que uma nova tentativa sua vire mensagem duplicada. - Trate o 422
number_not_on_whatsappremovendo o telefone da lista, em vez de tentar variações.
Quais identificadores existem?
| Formato | O que é |
|---|---|
5547999999999 |
Telefone, só dígitos, com código do país |
[email protected] |
O mesmo telefone como identificador (JID) de conta |
[email protected] |
Grupo |
173074381074537@lid |
Identificador interno de uma pessoa, sem telefone |
...@newsletter |
Canal |
Mais termos no glossário. Para o resto do fluxo de envio, veja os primeiros passos.
Veja também
- Verificar número com WhatsApp pela API
- Enviar imagem, vídeo e áudio no WhatsApp via API
- Erros e limites da API de WhatsApp
Índice completo: todos os guias. Sobre o produto: visão geral da API de WhatsApp da ProxyBox.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026. Prova do nono dígito feita em 10/11/2026 com um número real; revisado em 11/11/2026 contra a versão 1.1 da API.