Números Brasileiros

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:

  1. 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.
  2. 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 com RECIPIENT_NOT_ON_WHATSAPP. O envio funciona com o número em QUALQUER uma das duas formas.
  3. Consistência de eventos: o message.sent carrega o mesmo phone/chat que os eventos message.received da mesma conversa (resolvido pelo histórico armazenado), independente do formato que você enviou no to — nunca dois "phones" diferentes para o mesmo contato.

Aplicado em todos os pontos que recebem números do usuário:

  • Campo to em mensagens
  • contact_id em block/unblock
  • participants em grupos
  • numbers em 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 phone exatamente como recebido.