Cómo preparar una lista CSV o TXT para verificar números de WhatsApp en tiempo real

Una guía práctica de flujo de trabajo para preparar una lista CSV o TXT de números de teléfono para verificaciones de WhatsApp en tiempo real: formato E.164, elección del tipo de servicio y obtención de señales de presencia de cuenta desde los endpoints síncronos individual y múltiple.

WA Lookup verifica la presencia de cuentas de WhatsApp en tiempo real: envíe un número al endpoint de verificación síncrona, o hasta 100 números al endpoint múltiple síncrono POST /api/v1/batch-check, y los resultados completados se devuelven en la respuesta HTTP de la solicitud, sin ningún trabajo que esperar. Para procesar una lista CSV o TXT, dé a cada identificador un formato estrictamente conforme al estándar internacional de numeración E.164, elimine los caracteres no numéricos y los prefijos locales, y elija el tipo de servicio que necesita su flujo de trabajo: ws para el estado básico de registro, ws_avatar para incluir la disponibilidad de avatar o ws_business para identificar cuentas de WhatsApp Business. Un archivo completo que supere con creces una solicitud en tiempo real también puede subirse como tarea masiva asíncrona (subir, esperar, descargar).

Las señales de verificación de WhatsApp

Al preparar una lista CSV o TXT para verificaciones en tiempo real, el primer paso es determinar qué señal de presencia de cuenta respalda su flujo de trabajo concreto. WA Lookup ofrece tres tipos de servicio distintos, todos accesibles a través de los mismos endpoints síncronos. El parámetro service_type controla qué campos se devuelven en la respuesta.

Verificación básica de registro (ws)

El tipo de servicio ws confirma si un número de teléfono enviado está registrado actualmente en WhatsApp. Esta verificación devuelve un campo registered, que proporciona una señal de presencia de cuenta sencilla. Orienta las decisiones internas sobre qué números de su archivo CSV o TXT están asociados a una cuenta de WhatsApp en el momento de la verificación.

Verificación con enriquecimiento de avatar (ws_avatar)

El tipo de servicio ws_avatar incluye la verificación básica de registro y añade capacidades de enriquecimiento de perfil. Además del estado registered, esta verificación devuelve un valor booleano avatar que indica la disponibilidad de avatar y una cadena avatar_url. El campo de URL queda vacío cuando no hay ninguna URL disponible. Este contexto adicional puede ser un dato más, junto con otras verificaciones, al revisar perfiles de usuario.

Verificación de cuenta Business (ws_business)

El tipo de servicio ws_business comprueba el registro en WhatsApp e identifica si la cuenta utiliza WhatsApp Business. Devuelve un valor booleano business. Esta señal ayuda a los equipos a segmentar sus listas distinguiendo las cuentas estándar de los perfiles empresariales, lo que permite un enrutamiento más ajustado en el flujo de trabajo.

Cómo preparar su archivo de datos

El requisito más importante para procesar una lista CSV o TXT mediante verificaciones en tiempo real es dar un formato correcto a los datos. WA Lookup exige que todos los números se envíen en formato E.164. E.164 es un plan internacional de numeración telefónica que asigna a cada dispositivo un identificador único a escala mundial. Para preparar su archivo CSV o TXT:

1. Incluya el código de país: cada número debe comenzar con el código internacional de país correspondiente.
2. Elimine los caracteres de formato: quite de su lista los espacios, guiones, paréntesis y cualquier otro carácter no numérico.
3. Omita los ceros iniciales: elimine los prefijos troncales locales (a menudo un cero inicial) que no forman parte del código de marcación internacional.

Por ejemplo, un número de Estados Unidos debe escribirse como una cadena continua de dígitos que empiece por el código de país (por ejemplo, 1). Confirmar que toda su lista cumple el estándar E.164 ayuda a evitar errores de formato durante el proceso de verificación síncrona. Un archivo de entrada limpio y estandarizado es esencial para obtener señales de presencia de cuenta precisas para cada número enviado.

Cómo enviar su lista a verificación

Una vez que su lista CSV o TXT tenga el formato correcto, puede enviar los identificadores a la plataforma WA Lookup. La vía principal es síncrona: los resultados se devuelven en la misma respuesta HTTP que la solicitud, en lugar de entregarse más tarde. Para los equipos técnicos que integran el servicio, utilice POST /api/v1/check para un identificador o el endpoint múltiple síncrono POST /api/v1/batch-check para hasta 100 identificadores. Ambas solicitudes requieren un encabezado X-API-Key y un encabezado Content-Type: application/json. El cuerpo de la verificación individual contiene service_type e identifier; el cuerpo múltiple contiene service_type e identifiers. Siga las indicaciones de concurrencia de la documentación de la API. Un archivo CSV o TXT completo que supere con creces una solicitud en tiempo real también puede subirse como tarea masiva asíncrona; al enviarlo, usted elige el país al que pertenecen los números, y la lista debe corresponder esencialmente a ese único país. Las verificaciones fallidas, agotadas por tiempo o indeterminadas no conservan el cargo. Consulte la página de precios para conocer los detalles de facturación vigentes.

Cómo interpretar sus resultados

En una verificación de WhatsApp completada, el objeto data devuelto contiene service_type, identifier y registered; ws_avatar incluye además avatar y avatar_url, mientras que ws_business incluye business. Los campos internos de registro, transacción, estado y facturación no se devuelven. El resultado registered informa de los campos de estado de WhatsApp disponibles en el momento exacto de la verificación. Es importante comprender los límites de esta señal de presencia de cuenta. Además, el proceso de verificación no informa de la presencia en línea, del historial de mensajes ni del consentimiento de contacto. Tampoco indica si se podrá contactar con éxito con el número ni si los mensajes se entregarán. La señal simplemente informa a su base de datos interna sobre el registro en la plataforma, lo que puede ser un dato más, junto con otras verificaciones, al organizar su CRM o enrutar registros.

Preguntas frecuentes

¿Qué formato se exige para los números de teléfono?

Todos los números de teléfono deben enviarse estrictamente en formato E.164. Este plan internacional de numeración exige el código de país y la eliminación de todos los caracteres no numéricos, los espacios y los ceros iniciales locales.

¿Puedo comprobar el estado de WhatsApp Business en toda una lista?

Sí; al seleccionar el tipo de servicio ws_business, puede comprobar tanto el estado básico de registro como si la cuenta utiliza WhatsApp Business. Se devuelve un valor booleano específico que indica la presencia de una cuenta Business, tanto en una verificación individual como en una solicitud múltiple síncrona.

¿Qué ocurre si una verificación falla?

Las verificaciones fallidas, agotadas por tiempo o indeterminadas no conservan el cargo. Consulte la página de precios para conocer los detalles de facturación vigentes.

¿Los resultados de la verificación se entregan de forma asíncrona?

No en la vía principal. Los endpoints síncronos individual y múltiple devuelven el resultado completado en la misma respuesta HTTP que la solicitud. También está disponible, como complemento, una tarea masiva asíncrona (subir, esperar, descargar) para una lista grande completa, pero para las verificaciones cotidianas los endpoints síncronos son la opción recomendada.