Cómo validar y normalizar números de teléfono utilizando la librería libphonenumber de Google

Descripción general

Los números de teléfono incorrectos o incompletos son una de las principales causas de fallas en la entrega de mensajes a través de canales como WhatsApp, SMS y RCS.
Cuando los usuarios ingresan números inválidos (por ejemplo, sin código de país, líneas fijas en lugar de móviles o con errores tipográficos), los mensajes no se pueden entregar.

Implementar un proceso de validación y normalización de números telefónicos permite garantizar que los números se almacenen y procesen en un formato coherente, reduciendo los errores y mejorando la tasa de entrega en todas las comunicaciones.

Importancia de validar los números de teléfono

Antes de enviar cualquier mensaje, es necesario que el número cumpla con tres condiciones básicas:

1. Debe ser válido en un país específico.
   Ejemplo: 0412 123 4567 puede ser válido en Venezuela, pero no en Colombia.

2. Debe estar formateado de manera uniforme.
   Un formato estándar asegura que todas las plataformas —tu aplicación, las API de Messangi y WhatsApp— interpreten el número de forma correcta.

3. Debe ser accesible a través del canal adecuado.
   No todos los números móviles válidos están registrados en WhatsApp o pueden recibir SMS.

Recomendaciones y buenas prácticas

1. Validar desde el punto de captura

La mejor forma de evitar errores es validar los números en el momento en que el usuario los ingresa.

• Utiliza un selector de país que aplique automáticamente el código de país.

• Muestra mensajes de validación en tiempo real (por ejemplo: “Número válido” o “Formato incorrecto”).

• Restringe el campo de entrada para aceptar solo valores numéricos y elimina automáticamente espacios o caracteres especiales.

• Ofrece un ejemplo del formato esperado, por ejemplo: “Ejemplo para EE. UU.: (305) 555-1234”.

2. Almacenar los números en formato E.164

El formato E.164 es el estándar internacional reconocido por la mayoría de las plataformas de mensajería.
Formato:

+<CódigoPaís><NúmeroDeSuscriptor>

Ejemplos:

• Estados Unidos: +12015550123

• México: +525512345678

• Jamaica: +18765551234

Almacenar los números en este formato garantiza coherencia y facilita la integración con las API de Messangi y otros sistemas.

3. Validar tanto del lado del cliente como del servidor

La validación en el lado del cliente mejora la experiencia del usuario, pero la validación en el servidor garantiza la integridad de los datos.

• Validación del lado del cliente: evita que se envíen datos incorrectos.

• Validación del lado del servidor: asegura que todos los números procesados cumplan con las reglas de formato y país.

4. Filtrar únicamente números móviles

Si el canal de envío es WhatsApp o SMS, se deben excluir automáticamente los números de líneas fijas.
La librería libphonenumber puede identificar el tipo de número (móvil, fijo, gratuito, etc.) en la mayoría de los países.

5. Implementar confirmación o verificación del número

Si los usuarios suelen cometer errores al ingresar su número:

• Implementa verificación por código OTP vía WhatsApp o SMS.

• Usa botones o enlaces Click-to-WhatsApp para capturar automáticamente números verificados cuando el usuario inicia la conversación.

6. Monitorear y analizar los resultados de validación

Registra y analiza:

• El porcentaje de números inválidos ingresados.

• Los errores de validación más comunes (falta de código de país, longitud incorrecta, etc.).

• Las tasas de fallas en la entrega de mensajes por canal.

Estos datos ayudan a mejorar continuamente las reglas de validación y la experiencia del usuario.

Implementación técnica con libphonenumber

Acerca de libphonenumber

libphonenumber es una librería de código abierto desarrollada por Google que permite analizar, validar y formatear números de teléfono internacionales.
Sus principales funcionalidades son:

• Validar números de acuerdo con las reglas de cada país.

• Convertirlos a formatos estandarizados (E.164, nacional, internacional).

• Identificar el tipo de número (móvil, fijo, gratuito, etc.).

Esta librería es ampliamente utilizada por plataformas de comunicación y aplicaciones que gestionan números internacionales.

Instalación

JavaScript / Node.js

npm install libphonenumber-js

Python

pip install phonenumbers

Java

<dependency>
  <groupId>com.googlecode.libphonenumber</groupId>
  <artifactId>libphonenumber</artifactId>
  <version>8.13.31</version>
</dependency>

Ejemplo en JavaScript

import { parsePhoneNumberFromString } from 'libphonenumber-js'

const input = '3055551234'
const country = 'US'

const phoneNumber = parsePhoneNumberFromString(input, country)

if (phoneNumber && phoneNumber.isValid()) {
  console.log('Formato E.164:', phoneNumber.number)
} else {
  console.log('Número inválido')
}

Ejemplo en Python

import phonenumbers

number = phonenumbers.parse("3055551234", "US")

if phonenumbers.is_valid_number(number):
    print(phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.E164))
else:
    print("Número inválido")

Resumen de buenas prácticas

Recursos adicionales

• Repositorio oficial de libphonenumber en GitHub

• Documentación de libphonenumber-js

• Librería phonenumbers para Python