Formato E.164 para verificações da API do WhatsApp: Como formatos locais prejudicam as consultas
Entenda o que é o E.164, como formatos locais prejudicam as verificações da API do WhatsApp e como normalizar números antes de enviá-los para consulta.
Define o formato E.164, mostra os erros de formato local que produzem resultados incorretos nas verificações do WhatsApp e apresenta uma rotina de normalização para fluxos de trabalho de API e arquivos.
O E.164 é o formato de numeração internacional da UIT: um código de país seguido pelo número nacional, com no máximo 15 dígitos, escrito em sua forma canônica com um sinal de mais inicial e sem espaços, traços ou prefixos de tronco. As verificações da API do WhatsApp esperam números nesta forma internacional, pois um formato local, como 07700 900123, não indica a qual país pertence. Normalizar cada número para o padrão E.164 antes da verificação garante que o resultado esteja vinculado ao número que você realmente pretendia consultar.
O que é o formato E.164
A ITU-T Recommendation E.164 define o plano de numeração internacional de telecomunicações públicas. Para o trabalho prático com dados, um número E.164 possui três propriedades:
- Começa com um código de discagem de país de um a três dígitos, como 1, 44, 55 ou 971.
- Continua com o número nacional significativo, sem o prefixo de tronco doméstico (geralmente um 0 inicial).
- Não tem mais de 15 dígitos no total, e a forma escrita canônica é um sinal de mais seguido apenas por dígitos, por exemplo, +447700900123.
O que o E.164 exclui é tão importante quanto o que ele inclui: nenhum prefixo de discagem internacional como 00 ou 011, nenhum parêntese, nenhum espaço, nenhuma extensão.
Como formatos locais prejudicam as verificações da API do WhatsApp
A maioria das páginas que ranqueiam sobre este tópico para na definição. O problema prático é como dados comuns de CRM se transformam em uma consulta errada. Estes são os padrões que causam isso:
| Valor armazenado | Problema | Resultado E.164 |
|---|---|---|
| 07700 900123 (registro do Reino Unido) | Tronco 0 mantido, sem código de país | +447700900123 |
| 0044 7700 900123 | Prefixo internacional 00 em vez de + | +447700900123 |
| (631) 555-1234 | Sem código de país; ambíguo fora dos EUA | +16315551234 se o registro for dos EUA |
| +44 (0) 7700 900123 | Tronco 0 opcional mantido dentro da forma internacional | +447700900123 |
| 5511987654321 em uma coluna de texto | O + inicial foi perdido quando uma planilha armazenou o valor como número | +5511987654321 |
A orientação da Meta sobre o WhatsApp Business Messaging Policy mostra o risco claramente no lado do envio: sem o sinal de mais e o código do país, o código do país da própria empresa pode ser adicionado, então "(631) 555-1234" enviado de um número comercial indiano poderia ser resolvido como +916315551234 em vez do número pretendido nos EUA. A mesma ambiguidade se aplica a qualquer verificação. Se a verificação for executada contra o número errado, seu resultado descreverá outra pessoa.
Uma rotina de normalização antes de verificar números
Execute estas etapas antes de qualquer verificação no WhatsApp, independentemente de os números passarem pela API ou por um arquivo.
- Armazene números como texto. Células de número em planilhas removem o sinal de mais e zeros à esquerda, e valores longos podem se transformar em notação científica.
- Mantenha o país com o registro. A normalização precisa de uma região padrão para números inseridos em formato local; utilize o campo de país do contato, não a localização da equipe de vendas.
- Analise com uma biblioteca mantida. A libphonenumber do Google analisa uma string bruta mais uma região em um código de país e número nacional, formatando-o para E.164. Seu
isPossibleNumberé uma verificação apenas de comprimento, enquantoisValidNumbertambém usa informações de prefixo para a região. - Coloque falhas em quarentena. Valores que não podem ser analisados ou que falham na validação vão para uma fila de revisão em vez de para o verificador.
- Remova duplicatas após a normalização. "07700 900123" e "+44 7700 900123" tornam-se o mesmo número apenas após esta etapa.
Estas etapas respondem a uma pergunta restrita: a string é um número internacional plausível para sua região? Se o número possui uma conta no WhatsApp é uma pergunta separada que apenas uma verificação de registro responde.
Usando E.164 com a API e arquivos do WA Lookup
A API em tempo real do WA Lookup aceita um número de telefone enviado no formato E.164 para POST /api/v1/check, juntamente com o cabeçalho X-API-Key e o service_type que seleciona a Verificação de registro no WhatsApp, a Verificação de foto de perfil do WhatsApp ou a Verificação de conta WhatsApp Business. O POST /api/v1/batch-check aceita até 100 números por solicitação, e a mesma normalização se aplica a cada número nela. Siga a documentação atual da API para o corpo da solicitação exato.
Tarefas de arquivos em lote têm suas próprias necessidades de formatação:
- Apenas TXT ou CSV, um número com código de país por linha.
- O arquivo deve conter essencialmente um país selecionado. Quando 10% ou mais dos números vêm de outros países, a pré-verificação rejeita o arquivo; portanto, separe por código de país após a normalização.
- Números da China continental (+86), Hong Kong (+852) e Macau (+853) não são aceitos em arquivos em lote; verificações únicas em tempo real suportam essas regiões.
Erros comuns de E.164 para detectar na revisão
- Assumir que todo número é doméstico. Uma região padrão é um fallback para entrada em formato local, não uma regra para cada linha.
- Remover o sinal de mais para armazenamento. Mantenha a forma canônica no CRM; converta apenas se um sistema específico exigir outra representação.
- Manter extensões. Remova o texto de extensão, como "ramal 204", antes de verificar; o E.164 não tem espaço para isso.
- Tratar a normalização como permissão. Um número registrado e formatado corretamente ainda precisa de opt-in antes do contato, conforme a WhatsApp Business Messaging Policy.
- Misturar formatos em uma coluna. Uma coluna normalizada usada para verificar e enviar evita que os resultados se desviem dos registros aos quais pertencem.
Perguntas frequentes
Como as equipes podem saber se um número armazenado já está no formato E.164?
O valor começa com um sinal de mais, contém apenas dígitos após ele, não possui zero de tronco após o código do país e tem 15 dígitos ou menos. Analisá-lo com uma biblioteca como a libphonenumber e formatá-lo de volta para E.164 deve retornar a mesma string.
O sinal de mais inicial importa para verificações e mensagens do WhatsApp?
Ele marca o número como internacional. A orientação da Meta recomenda incluir tanto o sinal de mais quanto o código do país, pois um número sem eles pode ser interpretado com o código do país do remetente. Para o WA Lookup, siga a documentação atual da API para a string exata esperada na solicitação.
O que deve acontecer com números que falham na normalização?
Envie-os para uma fila de revisão com o valor original e o país do registro. Verificar uma string ambígua ou malformada consome saldo e pode vincular um resultado a um número diferente.
Por que um arquivo em lote precisa de números de um único país?
Tarefas em lote são enviadas para um país selecionado, e a pré-verificação rejeita arquivos onde 10% ou mais dos números vêm de outros países. Normalizar para E.164 primeiro facilita a divisão de uma exportação mista por código de país.
Saiba mais
Escolha as informações do produto que se ajustam à próxima etapa do seu fluxo de trabalho.