O nono dígito no WhatsApp: por que alguns números não recebem a mensagem
Contas antigas do WhatsApp podem estar registradas sem o nono dígito. Veja por que o envio falha em silêncio e como a apiwpp descobre o endereço certo.
O relatório diz que a mensagem saiu. O cliente jura que não recebeu nada. Você confere o número no cadastro, está certo: DDD, o 9 na frente, oito dígitos depois. Manda de novo, mesmo resultado. Para a maioria dos contatos tudo funciona, e só alguns poucos, quase sempre clientes antigos, parecem viver num buraco negro.
Na maior parte das vezes, o culpado é o nono dígito. Os celulares brasileiros ganharam o 9 na frente há anos, mas muitas contas de WhatsApp continuam registradas com o número antigo, de oito dígitos. Quem monta o endereço do destinatário na mão, juntando os dígitos do cadastro, manda a mensagem para um endereço que ninguém usa.
Este guia explica de onde vem o problema, por que ele é silencioso, o que a apiwpp faz antes de cada envio para evitá-lo e o que o seu sistema ainda precisa fazer: formatar o campo to, verificar a base antes de mandar e lidar com os contatos que chegam sem telefone.
Por que o nono dígito ainda causa problema
Quando a numeração dos celulares brasileiros mudou, o número de telefone ganhou um 9 depois do DDD: 11 8888-7777 passou a ser 11 98888-7777. A mudança foi feita por etapas, DDD por DDD, e ninguém precisou trocar de chip.
O WhatsApp, porém, não identifica uma conta pelo número que você digita. Cada conta tem um endereço interno, o JID, gravado no momento do cadastro. Uma conta criada antes da mudança pode ter ficado registrada assim:
[email protected] conta antiga, sem o nono dígito
[email protected] o mesmo número no formato atual
Para quem conversa pelo aplicativo, essa diferença fica invisível: ninguém digita o endereço interno de um contato. Uma integração que fala o protocolo do WhatsApp Web não tem essa ajuda: ela precisa saber em qual endereço o número está registrado.
O erro de montar o JID na mão
O atalho mais comum em integrações caseiras é pegar os dígitos do cadastro e colar @s.whatsapp.net no fim. Funciona para a maioria dos contatos, e é exatamente isso que torna o bug difícil de achar.
Quando o palpite está errado, nada estoura. O servidor do WhatsApp aceita uma mensagem endereçada a um JID que ninguém usa, a biblioteca devolve sucesso e o seu sistema registra "enviada". A mensagem simplesmente nunca é entregue. Não há erro para capturar, não há exceção no log, só um cliente que não recebeu o lembrete da consulta.
A tentação seguinte é "corrigir" o número com uma regra própria: tirar o 9 de todos os celulares, ou colocá-lo quando faltar. Isso troca um problema por outro, porque a maioria das contas está no formato novo e uma parte está no antigo. Não existe regra fixa que acerte todos: só o próprio WhatsApp sabe em qual formato cada conta foi registrada.
Como a apiwpp descobre o endereço certo
A apiwpp não adivinha. Antes de cada envio, ela pergunta ao WhatsApp em qual endereço (JID) aquele número está registrado e manda a mensagem para o endereço que o WhatsApp responder. Uma conta antiga, registrada sem o nono dígito, recebe a mensagem mesmo quando você manda o número com ele.
Dois detalhes importam:
- A apiwpp nunca inclui nem remove o nono dígito por conta própria. Ela não aplica regra de formatação nenhuma ao número: quem decide o endereço é a resposta do WhatsApp.
- Um número que não está no WhatsApp falha na hora, sem novas tentativas. Em vez de uma mensagem "enviada" que some, você recebe um motivo claro:
not_on_whatsapp.
Na prática, o que antes era um erro silencioso vira um de dois resultados observáveis: a mensagem chega no endereço certo, ou o envio falha com um motivo que o seu sistema consegue tratar.
O formato do campo to
No POST /connections/{id}/send, o destinatário vai no campo to: o número com código do país e DDD, só dígitos. Sem +, sem espaço, sem parênteses, sem hífen.
curl -s -X POST "https://api.apiwpp.com/connections/$ID/send" \
-H "Authorization: Bearer $APIWPP_KEY" \
-H 'Content-Type: application/json' \
-d '{"to": "5511988887777", "message": "Olá! Sua consulta está confirmada para amanhã.", "clientRef": "consulta-8812"}'
A resposta é 202, porque o envio entra na fila do número:
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }
A verificação do endereço acontece quando a mensagem sai da fila, não no momento da requisição. Por isso um número fora do WhatsApp não aparece como erro na resposta do /send: ele chega pelo webhook, como você vai ver adiante. O guia de envio com Node.js mostra o fluxo completo da requisição à confirmação de entrega.
Normalize o número antes de enviar
O cadastro do seu sistema provavelmente tem números em todos os formatos: (11) 98888-7777, +55 11 98888-7777, 11988887777. Normalize tudo para só dígitos com o código do país antes de chamar a API. Um exemplo em JavaScript para números brasileiros:
// Digits only, with the country code. It never touches the ninth digit:
// the gateway asks WhatsApp which address the number is registered under.
export function toWhatsAppDigits(raw) {
const digits = String(raw).replace(/\D/g, '')
if (digits.startsWith('55') && digits.length >= 12) return digits
if (digits.length === 10 || digits.length === 11) return `55${digits}`
throw new Error(`Número inválido: ${raw}`)
}
toWhatsAppDigits('(11) 98888-7777') // '5511988887777'
toWhatsAppDigits('+55 11 98888-7777') // '5511988887777'
Repare no que a função não faz: ela não tira nem coloca o 9. Guarde o número como o cliente informou, no formato atual, e deixe a resolução do endereço com a apiwpp.
Enviar direto para um JID
O campo to também aceita um JID pronto, como [email protected] ou 11122233344455@lid, e nesse caso ele é usado exatamente como veio, sem consulta. Isso é útil para responder a quem escreveu para o seu número: o evento message.incoming traz o jid do remetente, e responder para ele garante que a resposta volta para a mesma conversa.
Evite o caminho inverso: montar um JID a partir dos dígitos do cadastro. É justamente o palpite que este guia inteiro recomenda não fazer.
Verifique os números antes de enviar
Para limpar uma base ou validar um cadastro no momento em que ele é feito, use POST /connections/{id}/contacts/check. Ele verifica até 100 números por requisição e diz, para cada um, se está no WhatsApp e em qual JID:
curl -s -X POST "https://api.apiwpp.com/connections/$ID/contacts/check" \
-H "Authorization: Bearer $APIWPP_KEY" \
-H 'Content-Type: application/json' \
-d '{"phones": ["5511988887777", "5511955550000"]}'
{
"results": [
{ "phone": "5511988887777", "exists": true, "jid": "[email protected]" },
{ "phone": "5511955550000", "exists": false }
]
}
O primeiro número existe, e o jid mostra que a conta está registrada no formato antigo, sem o nono dígito. O segundo não está no WhatsApp. Os resultados vêm na mesma ordem dos números enviados. A página de verificação de números resume o recurso.
A consulta é feita pelo próprio número conectado, como um envio. Por isso a chave precisa do escopo messages:send e a conexão precisa estar open; em outro status, a resposta é 400. Mais de 100 números numa requisição também respondem 400.
Para uma base maior, divida em lotes de 100:
const API = 'https://api.apiwpp.com'
async function checkNumbers(connectionId, phones) {
const results = []
for (let i = 0; i < phones.length; i += 100) {
const response = await fetch(`${API}/connections/${connectionId}/contacts/check`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.APIWPP_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ phones: phones.slice(i, i + 100) }),
})
if (!response.ok) throw new Error(`contacts/check: ${response.status}`)
const { results: batch } = await response.json()
results.push(...batch)
}
return results
}
Marque no cadastro quem voltou com exists: false e não coloque essas pessoas em nenhuma rotina de envio. Além de economizar requisições, isso mantém o histórico do número limpo, o que ajuda a evitar o bloqueio.
Quando o envio falha com not_on_whatsapp
Se um número fora do WhatsApp chegar ao /send mesmo assim, o envio falha na hora, sem novas tentativas. Quando a requisição tinha um clientRef, o seu webhook recebe message.send_failed:
{
"type": "message.send_failed",
"data": {
"clientRef": "consulta-8812",
"jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
"messageId": null,
"to": "5511955550000",
"reason": "not_on_whatsapp",
"attempts": 1
}
}
É por isso que vale mandar sempre um clientRef: sem ele, esse evento não existe e o seu sistema não fica sabendo que a mensagem nunca vai sair. Com ele, você encontra o registro original e marca o contato. O guia de webhooks mostra como receber e validar esses eventos.
Um detalhe: repetir o envio com o mesmo clientRef só devolve o job original com "duplicate": true. Se o cliente corrigir o número e você quiser tentar de novo, use um clientRef novo.
Encontrar o contato quando a mensagem chega
O nono dígito também aparece no caminho de volta. Todo evento de uma conversa individual traz dois campos de endereço:
| Campo | Conteúdo |
|---|---|
jid | O endereço do outro lado, como o WhatsApp mandou: …@s.whatsapp.net ou …@lid. Sempre presente |
phone | O telefone em E.164, como +5511988887777, ou null quando ainda não se sabe qual é |
O phone é o número como o WhatsApp o conhece. Uma conta antiga escreve para você como +551188887777, sem o 9, mesmo que o seu cadastro tenha o número com ele. Se o seu CRM procura o cliente comparando o telefone exato, esse cliente vira um contato novo e a conversa se perde.
A solução é procurar pelos dois formatos quando o número for um celular brasileiro:
// Both spellings of a Brazilian mobile, to find the customer in your records.
// Old WhatsApp accounts may be registered without the ninth digit.
export function phoneVariants(e164) {
const digits = e164.replace(/\D/g, '')
const withNine = /^55(\d{2})9(\d{8})$/.exec(digits)
if (withNine) return [digits, `55${withNine[1]}${withNine[2]}`]
const withoutNine = /^55(\d{2})([6-9]\d{7})$/.exec(digits)
if (withoutNine) return [digits, `55${withoutNine[1]}9${withoutNine[2]}`]
return [digits]
}
phoneVariants('+551188887777') // ['551188887777', '5511988887777']
Essa função serve só para procurar no seu banco. Para responder, use o jid que veio no evento, que já é o endereço certo.
LID: quando o evento chega sem telefone
Existe um segundo caso em que o número não bate: o LID. O WhatsApp identifica cada vez mais conversas por um identificador que não revela o telefone, como 11122233344455@lid, para proteger a privacidade dos usuários. O LID é estável para o contato, mas não tem relação nenhuma com o número.
Quando a apiwpp não consegue descobrir o telefone de um LID, o evento chega mesmo assim, com phone: null:
{
"type": "message.incoming",
"data": { "from": "11122233344455@lid", "jid": "11122233344455@lid", "phone": null, "body": "Posso remarcar para sexta?" }
}
Não tente adivinhar o telefone a partir do LID. Guarde a conversa pelo jid, como um contato provisório, e responda para esse mesmo jid: o campo to aceita um …@lid e o usa como veio.
contact.resolved: o telefone apareceu
Quando a conexão descobre o telefone de um LID que já chegou ao seu projeto com phone: null, o webhook recebe contact.resolved, uma vez por LID:
{
"type": "contact.resolved",
"data": {
"lid": "11122233344455@lid",
"jid": "[email protected]",
"phone": "+5511988887777",
"firstSeenAt": "2026-07-20T12:00:00.000Z",
"messageCount": 2,
"source": "lid-mapping"
}
}
Nesse momento, reatribua ao contato de data.phone todos os eventos anteriores cujo jid seja igual a data.lid, e junte a conversa provisória com a do telefone, se ela já existir. Procure esse telefone pelos dois formatos, com e sem o nono dígito, pelo mesmo motivo da seção anterior.
Alguns LIDs nunca são resolvidos, porque o WhatsApp não revela o telefone de todos os contatos. Eles continuam chegando com phone: null e sempre com o mesmo jid, então o contato provisório funciona por tempo indeterminado.
Um resumo do que fica com quem
| Tarefa | Quem faz |
|---|---|
| Descobrir em qual JID o número está registrado, com ou sem o nono dígito | A apiwpp, antes de cada envio |
Deixar o to só com dígitos, com país e DDD | O seu sistema |
| Verificar a base antes de enviar | O seu sistema, com contacts/check |
| Avisar que um número não está no WhatsApp | A apiwpp, com not_on_whatsapp |
Encontrar o cliente quando phone vem sem o 9 | O seu sistema, procurando pelos dois formatos |
| Guardar conversas por LID e juntar depois | O seu sistema, com contact.resolved |
A parte difícil, saber o endereço real de cada conta, fica com a API. O que sobra para você é organização de dados: formato consistente, verificação e busca tolerante. Para uma definição curta, veja o verbete nono dígito do glossário. Se o seu sistema é em Node.js, a página de integração com Node.js junta envio e webhook num exemplo só.
Como começar hoje
- Normalize os telefones do seu cadastro para só dígitos, com
55e o DDD, sem mexer no nono dígito. - Rode
contacts/checkna base em lotes de 100 e marque quem voltou comexists: false. - Mande sempre um
clientRefno/sende tratemessage.send_failedcomreason: not_on_whatsappno seu webhook. - Troque a busca de contatos por telefone exato pela busca nos dois formatos.
- Guarde as conversas por
jide reconcilie os LIDs quando chegarcontact.resolved. - Crie sua conta na apiwpp, conecte um número e teste com um contato antigo da sua agenda. Os planos por número estão em preços.
Perguntas frequentes
Preciso tirar o nono dígito dos números antigos antes de enviar?
Não. Mande o número no formato atual, com o 9, só dígitos e com o código do país. A apiwpp pergunta ao WhatsApp em qual endereço a conta está registrada e envia para ele, e nunca inclui nem remove o dígito por conta própria.
Por que a mensagem aparecia como enviada, mas não chegava?
Porque um JID montado na mão, com o formato errado, aponta para um endereço que ninguém usa. O WhatsApp aceita a mensagem e a biblioteca devolve sucesso, mas ela nunca é entregue. Consultar o endereço registrado antes do envio elimina esse palpite.
Quantos números o contacts/check verifica de uma vez?
Até 100 números por requisição. Para bases maiores, divida em lotes. A chave precisa do escopo messages:send e a conexão precisa estar open, porque a consulta é feita pelo próprio número conectado.
O que acontece se eu enviar para um número que não tem WhatsApp?
O envio falha na hora, sem novas tentativas. Se a requisição tinha um clientRef, o seu webhook recebe message.send_failed com reason: not_on_whatsapp, e você pode marcar o contato no cadastro.
Por que o campo phone do webhook vem sem o 9?
Porque ele traz o número como o WhatsApp o conhece, e contas antigas podem estar registradas sem o nono dígito. Ao procurar o cliente no seu banco, compare os dois formatos. Para responder, use o jid do evento.
O que é um evento com phone igual a null?
É uma conversa identificada por um LID, um identificador que não revela o telefone. Guarde a conversa pelo jid e responda para ele. Se o telefone for descoberto depois, chega contact.resolved com o LID e o telefone para você juntar as conversas.
Leia também: