Gestión programática de nombres de usuario de WhatsApp Business

Una guía técnica para integrar verificaciones síncronas de registro, avatar y cuenta de empresa de WhatsApp en los flujos de trabajo del CRM mediante el endpoint POST /api/v1/check.

La correspondencia programática de identidades de WhatsApp consiste en utilizar el endpoint documentado POST /api/v1/check para verificar el estado de registro, la disponibilidad del avatar y los tipos de cuenta de empresa. Al enviar números en formato E.164 con la carga service_type adecuada, los equipos reciben datos JSON síncronos en la misma respuesta HTTP. Esta señal de presencia de cuenta ayuda a enriquecer los registros del CRM, facilita la limpieza de las listas de leads y orienta los flujos de enrutamiento automatizados, lo que da a los equipos de operaciones el contexto necesario para segmentar contactos sin depender de sondeos asíncronos ni de webhooks.

El papel de las verificaciones programáticas de WhatsApp

Integrar señales de presencia de cuenta de WhatsApp en las operaciones empresariales ayuda a los equipos a mantener bases de datos más limpias y favorece flujos de comunicación más eficientes. Cuando las organizaciones recopilan números de teléfono a través de formularios de registro, campañas de captación de leads o portales de atención al cliente, esos números suelen carecer de contexto sobre su presencia en plataformas de mensajería. Al verificar estos números de forma programática antes de iniciar el contacto, los equipos de operaciones pueden segmentar sus listas de contactos según el registro activo en la plataforma. Este proceso facilita la limpieza de las listas de leads al identificar qué registros están asociados a una cuenta de WhatsApp y cuáles no. Además, orienta las decisiones de enrutamiento automatizado. Este enfoque programático ayuda a mantener la precisión de los datos y proporciona a los equipos el contexto necesario para estructurar eficazmente sus canales de comunicación.

Cómo interpretar las señales de identidad de WhatsApp

La plataforma ofrece tres tipos de servicio distintos a través de un único endpoint, lo que permite a los desarrolladores solicitar el nivel de detalle concreto que requiere su flujo de trabajo. Cada tipo de servicio controla qué campos se devuelven en la respuesta JSON y qué coste de saldo se aplica.

• Verificación de registro (ws): es la verificación básica. Evalúa el número E.164 enviado y devuelve un campo registered, que proporciona una señal directa de presencia de cuenta en la plataforma estándar de WhatsApp.
• Verificación de avatar (ws_avatar): esta verificación incluye el estado de registro básico y añade datos de enriquecimiento del perfil. Devuelve un booleano avatar que indica si hay un avatar disponible y una cadena avatar_url que está vacía cuando no hay URL disponible.
• Verificación de cuenta de empresa (ws_business): diseñada para la segmentación B2B, esta verificación devuelve el estado de registro básico junto con un booleano business. Esta señal concreta ayuda a los equipos a identificar si el contacto utiliza una cuenta de WhatsApp Business.

Para una verificación de WhatsApp completada, el data devuelto contiene service_type, identifier y registered; ws_avatar incluye además avatar y avatar_url, mientras que ws_business incluye business. No se devuelven campos internos de registro, transacción, estado ni facturación.

Implementación de flujos de trabajo síncronos con la API

La integración técnica se basa en un contrato de solicitud síncrono y sencillo. Como los resultados son síncronos, se devuelven en la misma respuesta HTTP que la solicitud. Un CRM puede mantener un registro en memoria, realizar la llamada a la API y aplicar de inmediato la señal devuelta al flujo de trabajo. El contrato de solicitud documentado requiere enviar una solicitud al endpoint POST /api/v1/check. La solicitud debe incluir dos cabeceras: X-API-Key, que contiene su clave de autenticación, y Content-Type: application/json. El cuerpo JSON debe contener dos campos:

• service_type: un valor de cadena ws, ws_avatar o ws_business.
• identifier: el número de teléfono con formato del estándar E.164.

Para respaldar esta integración, el panel de la plataforma ofrece herramientas administrativas completas. Los equipos de desarrollo y operaciones pueden gestionar las claves API, supervisar su saldo, revisar el historial de verificaciones y acceder a informes por producto. El panel también muestra las verificaciones recientes, las métricas de gasto de saldo y la actividad de la cuenta para ayudar a supervisar el uso de la API y el volumen de los flujos de trabajo.

Buenas prácticas para la integridad de los datos y el enrutamiento

Al integrar verificaciones programáticas en un entorno de producción, es fundamental establecer expectativas precisas sobre lo que representan los datos. Un resultado registrado informa de los campos de estado de WhatsApp disponibles en el momento exacto de la verificación. Sirve estrictamente como señal de presencia de cuenta. No verifica el estado en línea, la hora de última conexión, el historial de mensajes ni el consentimiento del contacto. Las verificaciones fallidas, con tiempo de espera agotado o indeterminadas no conservan el cargo. Consulte la página de precios para conocer los detalles de facturación actuales.

Preguntas frecuentes

¿Cuál es la diferencia entre una verificación de registro y una verificación de cuenta de empresa?

Una verificación de registro estándar (con el tipo de servicio ws) devuelve una señal de presencia de cuenta que indica si el número E.164 enviado está registrado en WhatsApp. Una verificación de cuenta de empresa (con el tipo de servicio ws_business) devuelve el mismo estado de registro, pero añade un campo booleano business que indica si la cuenta utiliza WhatsApp Business.

¿Necesito configurar webhooks para las verificaciones de WhatsApp?

No. Todas las verificaciones son síncronas. Los resultados se devuelven en la misma respuesta HTTP que la solicitud inicial, lo que elimina la necesidad de configurar webhooks o de implementar lógica de sondeo asíncrono en su aplicación.

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

Todos los números de teléfono enviados deben tener el formato del estándar del plan internacional de numeración telefónica E.164.

¿Un estado registrado significa que puedo enviar un mensaje al usuario?

Un resultado registrado es estrictamente una señal de presencia de cuenta disponible en el momento de la verificación. No informa de la presencia en tiempo real, el historial de mensajes, el consentimiento del contacto ni de si el número puede recibir un mensaje correctamente.

¿Cómo se facturan las verificaciones fallidas o indeterminadas?

Las verificaciones fallidas, con tiempo de espera agotado o indeterminadas no conservan el cargo. Consulte la página de precios para conocer los detalles de facturación actuales.