Número de WhatsApp no Brasil: E.164 e o nono dígito na API

Número de WhatsApp no Brasil: E.164 e o nono dígito na API

Para o WhatsApp no Brasil, guarde cada número em E.164 com o nono dígito nos celulares (sinal de mais, 55, DDD e nove dígitos começando em 9) e use uma chave de comparação própria, porque o identificador devolvido pela API pode vir sem o nono dígito. Com uma única função de normalização na entrada e uma regra de deduplicação, o mesmo cliente deixa de aparecer duas vezes no CRM, no histórico de conversas e nas filas de atendimento.

Principais pontos

• E.164 é o formato internacional de numeração: sinal de mais, código do país e número, sem espaços, parênteses ou hífens. Um celular brasileiro fica como +55, DDD de dois dígitos e nove dígitos.
• O mesmo celular pode chegar com e sem o nono dígito, dependendo da origem: digitação manual, formulário, planilha importada ou retorno da API.
• A normalização deve acontecer na borda do sistema, em código determinístico, antes de qualquer gravação ou envio. Não deixe um modelo de IA decidir isso.
• Guarde três informações separadas: o número canônico, o identificador que a API devolveu e uma chave de comparação para detectar duplicados.
• Registre cada normalização e cada fusão de contatos em log e teste com números de teste reais antes de ligar o agente em produção.

Como é um número brasileiro no formato E.164?

E.164 é a recomendação internacional da ITU para numeração telefônica. Na prática, ela define um número como o sinal de mais, o código do país e o número nacional, com no máximo quinze dígitos no total. Não há separadores nem zeros de discagem.

No Brasil, o código do país é 55. Depois dele vem o DDD, sempre com dois dígitos. Em seguida, o número do assinante: nove dígitos para celular, começando em 9, ou oito dígitos para telefone fixo, começando entre 2 e 5.

Exemplos com dados fictícios:

• Celular canônico: +5511987654321
• Mesmo celular sem o nono dígito: +551187654321
• Fixo: +551132654321

O segundo exemplo é o que causa problema. Ele representa um assinante que o formato atual conhece com nove dígitos, mas que ainda circula com oito em agendas antigas, cadastros e, em alguns casos, em identificadores devolvidos por plataformas.

Por que o nono dígito quebra integrações e duplica contatos?

O problema não é o nono dígito em si, e sim a falta de uma regra única. Um sistema de atendimento sobre a API do WhatsApp costuma receber números de vários lugares ao mesmo tempo:

• Formulário do site, em que o cliente digita como quiser: com parênteses, com zero na frente, com ou sem 55.
• Planilha ou CRM antigo, em que muitos celulares ainda estão com oito dígitos.
• Webhook da API, que informa o identificador de quem escreveu.
• Digitação do atendente, que copia e cola de onde estiver.

Se cada origem grava o que recebeu, o banco passa a ter dois registros para a mesma pessoa. O atendente vê uma conversa dividida em dois contatos, o histórico se perde e uma campanha pode ser enviada duas vezes para o mesmo cliente. Se há um agente de IA respondendo, ele também perde contexto, porque a memória da conversa está presa a um registro e a pessoa reaparece em outro.

Um ponto que exige cuidado: o comportamento exato do identificador devolvido pela API em relação ao nono dígito depende do provedor e da conta, e pode mudar. Consulte a documentação oficial do seu provedor e trate o que ela não descreve como hipótese a verificar no seu próprio número de teste. A regra de projeto que vale em qualquer caso é não assumir que o número que você enviou será igual ao que volta.

Qual forma devo guardar como identificador do contato?

A recomendação é guardar três campos, cada um com uma função clara:

• Número canônico: E.164 com o nono dígito para celulares. É o que a equipe vê, exporta e usa para comparar com o CRM.
• Identificador da API: o valor exato que o provedor devolveu na última interação. Use esse valor para responder, caso o envio com o número canônico não funcione no seu provedor.
• Chave de comparação: 55, DDD e os oito últimos dígitos do número. Ela ignora a presença do nono dígito e serve só para encontrar duplicados.

A chave de comparação não é um identificador de pessoa. Ela apenas sinaliza que dois registros provavelmente são o mesmo celular. Dentro de um mesmo DDD, os oito últimos dígitos de um celular identificam a linha, então a colisão entre pessoas diferentes é improvável, mas a fusão deve ser registrada e reversível.

Como normalizar passo a passo

A função de normalização deve ser pequena, testada e usada por todas as entradas. A sequência abaixo é um ponto de partida. Confirme a regra de numeração vigente na Anatel antes de fixar as faixas de dígitos.

• Passo 1: remova tudo que não for dígito, incluindo espaços, parênteses, hífens e o sinal de mais. Guarde o texto original em outro campo, para auditoria.
• Passo 2: se o número vinha com sinal de mais e o código de outro país, pare. Não aplique regras brasileiras a números estrangeiros.
• Passo 3: remova zeros à esquerda, que vêm do hábito de discar o prefixo de longa distância. Se a sua base tem registros com código de operadora, trate esse caso à parte e valide com amostras reais.
• Passo 4: decida se o código do país já está presente pelo tamanho. Com 10 ou 11 dígitos, falta o 55. Com 12 ou 13 dígitos, ele já está. Não decida olhando se o número começa com 55, porque existe DDD 55.
• Passo 5: valide o DDD. Ele deve ter dois dígitos e o primeiro não pode ser zero.
• Passo 6: olhe o número do assinante. Se tem oito dígitos e começa entre 6 e 9, é um celular no formato antigo: insira o 9 na frente. Se tem oito dígitos e começa entre 2 e 5, é fixo: marque como fixo e não insira nada.
• Passo 7: monte o canônico no formato +55, DDD e número do assinante.
• Passo 8: gere a chave de comparação com 55, DDD e os oito últimos dígitos.
• Passo 9: se algo não encaixar, rejeite e mande para revisão humana. Adivinhar um dígito é pior do que pedir confirmação.

Esse trecho de lógica deve ser código comum, com testes automatizados. Um modelo de linguagem pode errar um dígito sem avisar, e uma função determinística não. Se o seu fluxo roda em uma ferramenta de automação, concentre a regra em um único passo reutilizável. O artigo sobre n8n com WhatsApp Cloud API mostra onde esse passo costuma entrar no fluxo de atendimento.

Como evitar contatos duplicados no CRM e no atendimento?

Normalizar na entrada resolve os casos novos. Para a base existente e para os casos de borda, use um guia de decisão simples quando a chave de comparação encontrar um registro já existente:

• Se o canônico é idêntico, é o mesmo contato. Atualize o registro e não crie outro.
• Se a chave de comparação é igual mas o canônico difere só pelo nono dígito, trate como o mesmo contato, atualize o canônico para a versão com nove dígitos e guarde o valor antigo como alias.
• Se a chave é igual mas o nome é muito diferente, não funda automaticamente. Envie para revisão humana, pois pode ser um número reaproveitado ou um erro de cadastro.
• Se o DDD é diferente, são contatos diferentes, mesmo que os oito últimos dígitos coincidam.
• Se o contato já está marcado como sem permissão para mensagens ativas, preserve essa marca na fusão. Perder esse registro por causa de uma duplicata é um risco real. O artigo sobre opt-in no WhatsApp trata de como coletar e guardar essa permissão.

Para a base antiga, rode a normalização em modo de simulação primeiro. Gere um relatório de pares candidatos a fusão, deixe uma pessoa da operação revisar uma amostra e só então aplique. Guarde um log de cada fusão com o registro de origem, o de destino e a data, para desfazer se necessário.

Outra fonte de duplicidade, diferente da de numeração, é o próprio webhook. Plataformas de mensagens podem reenviar o mesmo evento quando não recebem confirmação. Por isso, além do número, use o identificador da mensagem como chave de idempotência. A documentação da Stripe sobre requisições idempotentes e webhooks não trata de WhatsApp, mas descreve bem o padrão de entrega repetida e de processamento seguro, que se aplica aqui. Para tratar falhas e reenvios no fluxo, veja também erros e retentativas no n8n.

Cenário ilustrativo: a mesma cliente em dois contatos

Cenário ilustrativo: uma loja de materiais recebe pedidos de orçamento pelo site e atende pelo WhatsApp. A cliente Marina preencheu o formulário meses atrás com o celular em oito dígitos, e esse cadastro ficou no CRM. Hoje ela escreve pelo WhatsApp, e o sistema recebe o identificador dela sem o nono dígito em uma origem e com ele em outra.

Sem normalização, o atendente abre dois contatos chamados Marina. Um tem o orçamento, o outro tem a conversa de hoje. O agente de IA, sem acesso ao orçamento, pergunta de novo o que ela precisa.

Com a regra acima, o formulário já teria gravado o canônico com nove dígitos e a chave de comparação. Quando a mensagem chega, o sistema calcula a chave, encontra o contato existente, anexa a conversa a ele e guarda o identificador devolvido pela API num campo próprio. O atendente vê um só histórico e o agente consulta o orçamento correto.

Como testar e monitorar a normalização?

Trate a função de normalização como qualquer regra de negócio crítica: com uma tabela de casos de teste. Inclua pelo menos números com e sem 55, com zero na frente, com e sem nono dígito, fixos, DDD 55, números com sinal de mais de outros países e entradas lixo. A abordagem de ambientes simulados do artigo sobre testes de agentes de IA com mocks ajuda a validar o fluxo sem enviar mensagens reais a clientes.

Depois, observe o sistema rodando. Registre, para cada mensagem, o valor original, o canônico, a chave e a decisão tomada (novo contato, mesmo contato, enviado para revisão). Esses logs permitem investigar um erro depois e medir quantos casos caem em revisão manual. O primer de observabilidade do OpenTelemetry explica a lógica de logs, métricas e rastros que sustenta esse tipo de acompanhamento.

Há também a dimensão de privacidade. Telefone é dado pessoal sob a LGPD. Nos logs, mascare parte dos dígitos quando o log não precisar do número completo, limite quem acessa a tabela de fusões e defina por quanto tempo guarda o texto original digitado. A ANPD reúne orientações oficiais sobre o tema.

Como aplicar isso com método: mapear, limitar, pilotar, transferir

O método de trabalho cabe bem nesse problema. Em mapear, liste todas as origens de número (site, planilhas, CRM, API, digitação) e levante quantos contatos hoje têm possíveis duplicados, sem mexer em nada. Em limitar, centralize a regra em um único ponto de código, proíba que o agente de IA altere números e exija revisão humana para fusões ambíguas. Em pilotar, ligue a normalização em um fluxo real, com logs e um critério combinado, por exemplo a quantidade de duplicados novos por semana. Em transferir, entregue a documentação das regras, a tabela de testes e o procedimento de desfazer fusões, e decida com a equipe se expande, ajusta ou para.

Se a sua operação está começando a ligar IA ao WhatsApp, vale ler também o guia de como integrar IA no WhatsApp da empresa, porque a qualidade do cadastro de contatos é pré-requisito para qualquer agente funcionar bem.

Perguntas frequentes

O número do WhatsApp no Brasil deve sempre ter o nono dígito? Para celulares, a forma canônica que recomendamos guardar é com o nono dígito, no formato E.164. Isso não significa que toda API devolva o identificador assim, então mantenha também o valor devolvido pelo provedor e use a chave de comparação para ligar os dois.

Posso pedir para o agente de IA corrigir os números? Não é recomendável. Normalização é uma tarefa com regras claras e deve ser feita por código determinístico e testado. O agente pode, no máximo, pedir confirmação ao cliente quando a regra rejeitar um número, e a resposta ainda deve passar pela mesma função.

Como limpo uma base antiga que já tem duplicados? Rode a normalização em modo de simulação, gere um relatório de pares com a mesma chave de comparação, revise uma amostra com a equipe e só depois aplique as fusões. Guarde um log de cada fusão e preserve as marcas de permissão de contato, para poder desfazer e para não perder registros de opt-out.

A mesma regra serve para números de outros países? Não. As regras de nono dígito e de DDD valem para a numeração brasileira. Para números que chegam com sinal de mais e código de outro país, valide só o formato E.164 geral e não aplique o ajuste brasileiro, a menos que você tenha uma regra específica para aquele país.

Fontes

• ITU: Recomendação E.164, plano internacional de numeração
• Stripe: requisições idempotentes (exemplo de padrão de idempotência)
• Stripe: entrega e verificação de webhooks (exemplo de padrão)
• ANPD: Autoridade Nacional de Proteção de Dados