Formato E.164 para verificaciones de la API de WhatsApp: Cómo los formatos locales interrumpen las búsquedas
Qué es E.164, cómo los formatos locales interrumpen las verificaciones de la API de WhatsApp y una rutina de normalización para preparar números antes de verificarlos.
Define el formato E.164, muestra los errores de formato local que producen resultados de verificación de WhatsApp incorrectos y establece una rutina de normalización para flujos de trabajo de API y archivos.
E.164 es el formato de numeración internacional de la UIT: un código de país seguido del número nacional, con un máximo de 15 dígitos, escrito en su forma canónica con un signo más inicial y sin espacios, guiones ni prefijos de tronco. Las verificaciones de la API de WhatsApp esperan números en esta forma internacional porque un formato local como 07700 900123 no indica a qué país pertenece. Normalizar cada número a E.164 antes de verificarlo mantiene el resultado vinculado al número que usted realmente pretendía consultar.
Qué es el formato E.164
La ITU-T Recommendation E.164 define el plan de numeración internacional de telecomunicaciones públicas. Para el trabajo práctico con datos, un número E.164 tiene tres propiedades:
- Comienza con un código de llamada de país de uno a tres dígitos, como 1, 44, 55 o 971.
- Continúa con el número nacional significativo, sin el prefijo de tronco doméstico (a menudo un 0 inicial).
- No tiene más de 15 dígitos en total, y la forma escrita canónica es un signo más seguido solo por dígitos, por ejemplo +447700900123.
Lo que E.164 omite es tan importante como lo que incluye: no hay prefijo de marcado internacional como 00 o 011, ni paréntesis, ni espacios, ni extensiones.
Cómo los formatos locales interrumpen las verificaciones de la API de WhatsApp
La mayoría de las páginas que posicionan sobre este tema se detienen en la definición. El problema práctico es cómo los datos ordinarios de CRM se convierten en una búsqueda incorrecta. Estos son los patrones que lo causan:
| Valor almacenado | Problema | Resultado E.164 |
|---|---|---|
| 07700 900123 (registro del Reino Unido) | Se mantuvo el 0 de tronco, sin código de país | +447700900123 |
| 0044 7700 900123 | Prefijo internacional 00 en lugar de + | +447700900123 |
| (631) 555-1234 | Sin código de país; ambiguo fuera de EE. UU. | +16315551234 si el registro es de EE. UU. |
| +44 (0) 7700 900123 | Se mantuvo el 0 de tronco opcional dentro de la forma internacional | +447700900123 |
| 5511987654321 en una columna de texto | El + inicial se perdió cuando una hoja de cálculo almacenó el valor como número | +5511987654321 |
La WhatsApp Business Messaging Policy y la guía de Meta sobre el formato de números de teléfono muestran el riesgo claramente en el lado del envío: sin el signo más y el código de país, se puede anteponer el código de país del propio número de la empresa, por lo que "(631) 555-1234" enviado desde un número de empresa de la India podría resolverse como +916315551234 en lugar del número de EE. UU. previsto. La misma ambigüedad se aplica a cualquier verificación. Si la verificación se ejecuta contra el número incorrecto, su resultado describe a otra persona.
Una rutina de normalización antes de verificar números
Ejecute estos pasos antes de cualquier verificación de WhatsApp, ya sea que los números pasen por la API o se incluyan en un archivo.
- Almacene los números como texto. Las celdas de número de las hojas de cálculo eliminan el signo más y los ceros iniciales, y los valores largos pueden convertirse en notación científica.
- Mantenga el país con el registro. La normalización necesita una región predeterminada para los números ingresados en formato local; tómela del campo de país del contacto, no de la ubicación del equipo de ventas.
- Analice con una biblioteca mantenida. libphonenumber de Google analiza una cadena sin procesar más una región para obtener un código de país y un número nacional, y lo formatea a E.164. Su
isPossibleNumberes una verificación solo de longitud, mientras queisValidNumbertambién utiliza información de prefijo para la región. - Ponga en cuarentena los fallos. Los valores que no se pueden analizar o que no superan la validación van a una cola de revisión en lugar de al verificador.
- Elimine duplicados después de la normalización. "07700 900123" y "+44 7700 900123" se convierten en el mismo número solo después de este paso.
Estos pasos responden a una pregunta limitada: ¿es la cadena un número internacional plausible para su región? Si el número tiene una cuenta de WhatsApp es una pregunta distinta que solo responde una verificación de registro.
Uso de E.164 con la API y archivos de WA Lookup
La API en tiempo real de WA Lookup toma un número de teléfono enviado en formato E.164 para POST /api/v1/check, junto con el encabezado X-API-Key y el service_type que selecciona la Verificación de registro en WhatsApp, la Verificación de avatar de WhatsApp o la Verificación de cuenta de WhatsApp Business. POST /api/v1/batch-check acepta hasta 100 números por solicitud, y la misma normalización se aplica a cada número en ella. Siga la documentación actual de la API para conocer el cuerpo de solicitud exacto.
Las tareas de archivos masivos tienen sus propias necesidades de formato:
- Solo TXT o CSV, un número con código de país por línea.
- El archivo debe contener esencialmente un país seleccionado. Cuando el 10% o más de los números provienen de otros países, la verificación previa rechaza el archivo, por lo que debe dividir por código de país después de la normalización.
- Los números de China continental (+86), Hong Kong (+852) y Macao (+853) no se aceptan en archivos masivos; las verificaciones individuales en tiempo real limitadas admiten esas regiones.
Errores comunes de E.164 a detectar en la revisión
- Asumir que cada número es doméstico. Una región predeterminada es un respaldo para la entrada en formato local, no una regla para cada fila.
- Eliminar el signo más para el almacenamiento. Mantenga la forma canónica en el CRM; convierta solo si un sistema específico requiere otra representación.
- Mantener extensiones. Elimine el texto de extensión como "ext. 204" antes de verificar; E.164 no tiene espacio para ello.
- Tratar la normalización como permiso. Un número registrado y correctamente formateado aún necesita opt-in antes de realizar contactos bajo la WhatsApp Business Messaging Policy.
- Mezclar formatos en una columna. Una columna normalizada utilizada para verificar y enviar evita que los resultados se desvíen de los registros a los que pertenecen.
Preguntas frecuentes
¿Cómo pueden los equipos saber si un número almacenado ya está en formato E.164?
El valor comienza con un signo más, contiene solo dígitos después de él, no tiene un cero de tronco después del código de país y tiene 15 dígitos o menos. Analizarlo con una biblioteca como libphonenumber y formatearlo de nuevo a E.164 debería devolver la misma cadena.
¿El signo más inicial importa para las verificaciones y mensajes de WhatsApp?
Marca el número como internacional. La guía de Meta recomienda incluir tanto el signo más como el código de país porque un número sin ellos puede interpretarse con el código de país del remitente. Para WA Lookup, siga la documentación actual de la API para conocer la cadena exacta esperada en la solicitud.
¿Qué debería suceder con los números que fallan en la normalización?
Envíelos a una cola de revisión con el valor original y el país del registro. Verificar una cadena ambigua o mal formada consume saldo y puede adjuntar un resultado a un número diferente.
¿Por qué un archivo masivo necesita números de un solo país?
Las tareas masivas se envían para un país seleccionado, y la verificación previa rechaza los archivos donde el 10% o más de los números provienen de otros países. Normalizar a E.164 primero facilita la división de una exportación mixta por código de país.
Más información
Elija la información del producto que se ajuste al siguiente paso en su flujo de trabajo.