Pular para o conteúdo
apiwpp

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.

Equipe apiwpp · 11 min de leitura

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.

O mesmo número em dois formatos: só um deles é o endereço em que a conta está registrada no WhatsApp.

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:

CampoConteúdo
jidO endereço do outro lado, como o WhatsApp mandou: …@s.whatsapp.net ou …@lid. Sempre presente
phoneO 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.

Do cadastro à conversa: normalizar, verificar, enviar e reconciliar os contatos que chegam por LID.

Um resumo do que fica com quem

TarefaQuem faz
Descobrir em qual JID o número está registrado, com ou sem o nono dígitoA apiwpp, antes de cada envio
Deixar o to só com dígitos, com país e DDDO seu sistema
Verificar a base antes de enviarO seu sistema, com contacts/check
Avisar que um número não está no WhatsAppA apiwpp, com not_on_whatsapp
Encontrar o cliente quando phone vem sem o 9O seu sistema, procurando pelos dois formatos
Guardar conversas por LID e juntar depoisO 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

  1. Normalize os telefones do seu cadastro para só dígitos, com 55 e o DDD, sem mexer no nono dígito.
  2. Rode contacts/check na base em lotes de 100 e marque quem voltou com exists: false.
  3. Mande sempre um clientRef no /send e trate message.send_failed com reason: not_on_whatsapp no seu webhook.
  4. Troque a busca de contatos por telefone exato pela busca nos dois formatos.
  5. Guarde as conversas por jid e reconcilie os LIDs quando chegar contact.resolved.
  6. 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:

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.