20. Números Brasileiros#
A API resolve automaticamente a variância do nono dígito de números brasileiros (BR).
O problema real (dois casos opostos):
- Legado (contas anteriores ao 9º dígito, DDD >= 31): o WhatsApp registra o JID com 12 dígitos (
554192464230). Se o número chega com 13 (5541992464230), o 9 extra precisa ser removido. - Alocação moderna (o 9 é parte estrutural do número, ex.:
41 92005-3637): o WhatsApp registra o JID com 13 dígitos (5541920053637). O irmão de 12 dígitos (554120053637) tem formato de FIXO e não é a mesma conta — remover o 9 aqui fabricaria um destinatário inexistente.
Nenhuma regra estática de dígito/DDD acerta os dois casos — só a consulta de registro do WhatsApp sabe o formato canônico. A API trata assim:
- Normalização com guarda (
NormalizeRemoteJID): o 9 extra só é removido quando o número pós-remoção tem formato de celular legado (miolo começando 6-9).5541992464230→554192464230;5541920053637→ preservado. - Resolução de variante no envio (wwebjs): se a consulta de registro (
getNumberId) retorna "não registrado" para o número exato, o worker tenta o irmão do 9º dígito (55DD9XXXXXXXX↔55DDXXXXXXXX) antes de falhar comRECIPIENT_NOT_ON_WHATSAPP. O envio funciona com o número em QUALQUER uma das duas formas. - Consistência de eventos: o
message.sentcarrega o mesmophone/chatque os eventosmessage.receivedda mesma conversa (resolvido pelo histórico armazenado), independente do formato que você enviou noto— nunca dois "phones" diferentes para o mesmo contato.
Aplicado em todos os pontos que recebem números do usuário:
- Campo
toem mensagens contact_idem block/unblockparticipantsem gruposnumbersem check de contatos
Você não precisa se preocupar com o formato do número. Envie como você tem (com ou sem o 9) e a API resolve o registro real. Recomendação: para contatos que vieram de webhooks da própria API, reenvie o
phoneexatamente como recebido.