Integración de la API de WA Lookup para enriquecer perfiles de WhatsApp

Una guía técnica para desarrolladores sobre cómo implementar consultas síncronas de perfiles y avatares de WhatsApp con la API de WA Lookup.

La API de WA Lookup ofrece una interfaz REST síncrona que ayuda a los desarrolladores a automatizar el enriquecimiento de perfiles de WhatsApp. Al enviar una solicitud POST al endpoint /api/v1/check con un tipo de servicio concreto —ws, ws_avatar o ws_business— y un número de teléfono en formato E.164, la API devuelve de inmediato señales de presencia de cuenta directamente en la respuesta HTTP. Estas señales incluyen el estado de registro, la disponibilidad de avatar, las URL de avatar y los indicadores de cuenta Business, que pueden servir como datos de entrada para el enrutamiento en el CRM, la segmentación de audiencias y los flujos internos de apoyo a la toma de decisiones.

Introducción a la API de WA Lookup

Al integrar canales de comunicación en los flujos de trabajo de la empresa, los equipos técnicos necesitan señales de presencia de cuenta precisas para orientar su lógica de enrutamiento y segmentación. WA Lookup ofrece verificaciones síncronas individuales y de lotes pequeños sobre el registro en WhatsApp, la disponibilidad de avatar y el estado de cuenta Business. El endpoint individual verifica un identificador y el endpoint múltiple síncrono admite hasta 100 identificadores; ambos devuelven los datos en la misma respuesta HTTP. Esta arquitectura síncrona permite tomar decisiones de inmediato sin webhooks asíncronos, infraestructura de sondeo ni colas de procesamiento por lotes. Es fundamental comprender los límites de esta señal de presencia de cuenta. Un resultado registrado informa de los campos de estado de WhatsApp disponibles en el momento exacto de la verificación. No informa de la presencia en línea, del historial de mensajes, del consentimiento del usuario ni de si el número puede contactarse actualmente. En cambio, forma parte de un flujo de trabajo más amplio y ayuda a los equipos a revisar registros y priorizar el contacto en función de la presencia en la plataforma.

Los tipos de servicio

La API de WA Lookup concentra sus capacidades en un único endpoint síncrono. Los desarrolladores controlan qué señales de perfil concretas se obtienen —y qué coste de saldo se aplica— modificando el parámetro service_type en el cuerpo de la solicitud. La API admite tres tipos de servicio distintos:

• Verificador de WhatsApp (ws): es el tipo de servicio básico. Su alcance se limita estrictamente a confirmar si un número de teléfono enviado está registrado en WhatsApp. Proporciona una señal básica de registro en la plataforma.
• Verificador de avatar de WhatsApp (ws_avatar): este tipo de servicio amplía la verificación básica con enriquecimiento de perfil. Además de comprobar el registro en WhatsApp, comprueba la disponibilidad de avatar y devuelve un campo avatar_url. El campo de URL queda vacío cuando no hay ninguna URL disponible.
• Verificador de WhatsApp Business (ws_business): este tipo de servicio está pensado para flujos B2B. Comprueba el registro estándar en WhatsApp y, además, determina si la cuenta utiliza WhatsApp Business, lo que aporta una señal específica de perfil empresarial.

Al seleccionar el tipo de servicio adecuado, los product managers técnicos pueden ajustar la salida de la API a los requisitos exactos de su flujo de trabajo y asegurarse de que solo solicitan y consumen los datos necesarios para su caso de uso concreto.

Implementación técnica

Integrar la API de WA Lookup exige respetar un contrato de solicitud JSON y unas reglas de formato estrictas. Todas las interacciones se realizan a través del endpoint POST /api/v1/check. Para autenticarse y dar el formato correcto a la solicitud, los desarrolladores deben incluir encabezados específicos: el encabezado X-API-Key con la clave API activa y el encabezado Content-Type: application/json. El cuerpo JSON de la solicitud debe contener exactamente dos campos:

1. service_type: un valor de cadena "ws", "ws_avatar" o "ws_business".
2. identifier: el número de teléfono de destino, enviado estrictamente en formato E.164.

El formato E.164 es un plan internacional de numeración telefónica que garantiza que los números de teléfono no sean ambiguos a escala mundial. Un número en formato E.164 debe comenzar con un signo más (+), seguido inmediatamente del código de país y del número de abonado, sin espacios, guiones ni paréntesis (por ejemplo, +17253100591). Si no se utiliza el formato E.164, la verificación no se completará correctamente. Como la API es totalmente síncrona, la conexión HTTP permanece abierta mientras se realiza la verificación y los resultados se entregan en la respuesta HTTP inmediata.

Cómo interpretar las respuestas de la API

La API de WA Lookup devuelve un conjunto previsible de campos en cada respuesta de verificación, con campos adicionales según el service_type seleccionado. 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. Cuando service_type es ws, el resultado incluye únicamente el campo registered, junto con los valores service_type e identifier devueltos tal como se enviaron. Cuando service_type es ws_avatar, el esquema de respuesta se amplía con un campo avatar (un booleano que indica si hay un avatar configurado) y un campo avatar_url. avatar_url es una cadena vacía cuando no hay ninguna URL disponible. Cuando service_type es ws_business, el esquema de respuesta añade un campo business, un booleano que indica si el número registrado está asociado a una cuenta de WhatsApp Business.

Panel y gestión del uso

La gestión del uso de la API y la supervisión de los datos de entrada del flujo de trabajo se realizan desde el panel de la plataforma. El panel ofrece una gestión completa de claves API, de modo que los desarrolladores pueden generar y rotar de forma segura las claves necesarias para el encabezado X-API-Key. Para la supervisión operativa, el panel incluye funciones para controlar el saldo, revisar el historial de verificaciones y consultar informes por producto. Los equipos técnicos pueden supervisar las verificaciones recientes, analizar el gasto de saldo y ver la actividad de la cuenta para comprender sus patrones de uso y optimizar su integración. Revise el saldo y el historial de verificaciones en el panel; consulte la página de precios y la documentación de la API para conocer las reglas de facturación vigentes.

Preguntas frecuentes

¿La API de WA Lookup es síncrona?

Sí. Los endpoints en tiempo real son síncronos: los resultados se devuelven en la misma respuesta HTTP que la solicitud que los inicia. El endpoint de número individual verifica un identificador, y el endpoint múltiple síncrono admite hasta 100 identificadores sin trabajos, callbacks ni sondeo. Las listas más grandes se gestionan con un producto masivo asíncrono independiente, en el que usted sube un archivo y descarga el resultado más tarde.

¿Cuál es la diferencia entre los tipos de servicio ws y ws_avatar?

El tipo de servicio ws devuelve solo la señal básica de registro en WhatsApp. El tipo de servicio ws_avatar devuelve la señal de registro y, además, comprueba la disponibilidad de avatar, devolviendo una cadena avatar_url que queda vacía cuando no hay ninguna URL disponible.

¿Qué formato deben tener los números de teléfono?

Todos los números de teléfono enviados a la API deben tener el formato del estándar E.164. Esto requiere un signo más (+) seguido del código de país y del número de abonado, sin espacios ni caracteres especiales.