Formato E.164 de telefone: como converter e validar números

Por que as APIs de SMS e WhatsApp exigem E.164?

Porque o roteamento depende de um número sem ambiguidade. Um número sem código de país pode pertencer a vários países, e a plataforma poderia enviar ao mercado errado, aplicar as regras de sender ID erradas e cobrar a tarifa errada. Tarifas, registro de sender ID e horários de envio promocional são aplicados por país de destino, e o código do país é o que identifica o destino.

O que a Meta diz sobre os números do WhatsApp?

A documentação da Meta sobre os formatos de número de telefone de usuários do WhatsApp diz que sinais de mais, hífens, parênteses e espaços são aceitos nas requisições de envio de mensagem e recomenda enfaticamente incluir o sinal de mais e o código de chamada do país. Se o sinal de mais estiver ausente, o código de chamada do país do remetente é acrescentado ao número, o que pode levar a mensagem a um número errado. Exemplo da Meta: para um remetente na Índia (código 91), (631) 555-1234 é entregue a +916315551234, enquanto +1 (631) 555-1234 é entregue corretamente. A Meta também observa que, para o Brasil e o México, a Cloud API pode modificar o prefixo extra que aparece em alguns números, e chama isso de comportamento padrão.

A abordagem segura: guarde E.164 limpo e envie exatamente isso.

E no caso do SMS?

As APIs de SMS também esperam o número internacional completo. Algumas exigem os dígitos sem o sinal de mais; o formato varia entre APIs e protocolos, então consulte a documentação da API que você usa e teste com o seu próprio número. Veja enviar SMS por API e enviar mensagem de WhatsApp por API para exemplos funcionais.

Como valido e normalizo números em código?

Use uma regex para uma verificação rápida de formato e uma biblioteca para a validação de verdade.

Uma verificação comum do formato E.164:

// Plus, a non-zero first digit, then 1 to 14 more digits: 15 digits at most
const E164 = /^\+[1-9]\d{1,14}$/;

function looksLikeE164(value) {
  return E164.test(value);
}

looksLikeE164("+971501234567"); // true
looksLikeE164("0501234567");    // false: no plus or country code
looksLikeE164("+0501234567");   // false: country codes do not start with 0

A regex verifica apenas tamanho e caracteres. Ela aceita +99999999999 mesmo que esse número não exista. Para validação de verdade, use a libphonenumber, biblioteca de código aberto do Google para analisar, formatar e validar números de telefone internacionais, disponível para Java, C++ e JavaScript, com portes da comunidade em outras linguagens. O README descreve isValidNumber como validação completa para uma região usando informações de tamanho e prefixo, e mostra como formatar um número analisado como E.164.

# pip install phonenumbers  (a Python port of libphonenumber)
import phonenumbers

def to_e164(raw, default_region):
    try:
        number = phonenumbers.parse(raw, default_region)  # e.g. "AE", "SA", "GB"
    except phonenumbers.NumberParseException:
        return None
    if not phonenumbers.is_valid_number(number):
        return None
    return phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.E164)

print(to_e164("050 123 4567", "AE"))   # +971501234567 if the number is valid for the UAE
print(to_e164("+44 7700 900123", "GB"))

Os portes são escritos por desenvolvedores externos, então avalie a qualidade do que escolher. Faça a análise com uma região padrão tirada do país do cliente e depois guarde o resultado E.164. Guarde também a entrada original, para poder analisar de novo se as regras mudarem.

Normalize no ponto de entrada, no formulário de cadastro, na importação do CRM ou na API, não na hora do envio. Um número escrito de duas formas vira dois contatos que recebem a mesma campanha.

Como corrijo números de telefone em uma planilha?

Formate a coluna de telefone como Texto antes de inserir ou colar os números. Os problemas mais comuns são:

A Microsoft documenta que o Excel remove zeros à esquerda e converte números grandes em notação científica, e que números inseridos antes de aplicar o formato Texto precisam ser inseridos de novo. Quando você abre um arquivo CSV diretamente, o Excel aplica a cada coluna os formatos padrão, então use o Assistente de Importação de Texto ou De Texto/CSV para marcar a coluna de telefone como texto.

Para uma lista de celulares dos Emirados guardada como 050 123 4567 na coluna A, esta fórmula monta o E.164 como texto:

="+971"&RIGHT(SUBSTITUTE(A2," ",""),9)

Ela mantém os últimos nove dígitos depois de remover os espaços, então só serve para números nesse formato. Copie o resultado e cole como valores antes de salvar em CSV. O formatador de números de telefone converte um número sem fórmula, e nosso guia de envio de SMS em massa pelo Excel ou CSV mostra o fluxo completo de importação.

Exemplo prático: limpando uma lista de clientes

A "Souq Rafiq" (fictícia), varejista de Dubai, exporta 8.000 contatos de três sistemas com números como 0501234567, 971 50 123 4567, +971-50-123-4567 e 00971501234567.

1. O analista adiciona uma coluna de país a partir do país de cobrança de cada cliente.
2. Um script analisa cada linha com o país como região padrão, de modo que os quatro formatos viram +971501234567.
3. As linhas que falham na validação vão para uma planilha de revisão em vez de serem enviadas.
4. Os duplicados são removidos depois da normalização, que reúne os quatro formatos em um só contato.
5. Uma consulta HLR sinaliza números inativos antes da campanha. Veja consulta HLR explicada.
6. A coluna limpa é guardada como Texto e importada.

Normalizar primeiro é o que faz a verificação de duplicados funcionar; antes disso, o mesmo cliente parecia quatro pessoas.

Quais são os erros mais comuns?

• Sempre remover o zero inicial. Alguns países, como a Itália, não têm prefixo de tronco.
• Manter o zero e acrescentar o código do país, resultando em +9710501234567.
• Enviar sem o sinal de mais ao WhatsApp, de modo que o código do país do remetente é acrescentado.
• Usar uma regex como validação. Ela verifica o formato, não a validade.
• Deixar o Excel tratar telefones como números, perdendo zeros ou passando para notação científica.
• Normalizar na hora do envio em vez de na entrada.
• Supor que formato válido significa número alcançável. Números portados ou desconectados ainda falham.
• Confiar em uma tabela estática. Os planos de numeração mudam; use uma biblioteca mantida.

Como a OmniChannels.ai ajuda

A OmniChannels.ai aceita números internacionais para SMS e WhatsApp por uma única API REST, e suas campanhas aceitam uploads de Excel e CSV com pré-visualização e filtro de duplicados. A BroadNet oferece HLR e consulta de números, para você verificar se um número bem formado está ativo. Leia a documentação da API de SMS e a documentação da API de WhatsApp para ver os campos exatos das requisições, ou fale com nossa equipe sobre o onboarding.