API de verificación de WhatsApp: Comprobación de registro desde su backend

Cómo los equipos de backend llaman a una API de verificación de WhatsApp, eligen entre las verificaciones de registro, de avatar y de cuenta de empresa, y gestionan los resultados indeterminados.

Una API de verificación de WhatsApp toma un número de teléfono desde su servidor y devuelve, en la misma respuesta, si había una cuenta de WhatsApp registrada en ese número en el momento de la comprobación. En WA Lookup, un número se envía a POST /api/v1/check con la clave en el encabezado X-API-Key y un 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, mientras que POST /api/v1/batch-check acepta hasta 100 números en una única solicitud síncrona. Una comprobación que no puede decidirse devuelve un código de negocio distinto de cero, que el código de backend debe tratar como "intentar de nuevo más tarde" en lugar de como una respuesta de No registrado.

Qué ofrece una API de verificación de WhatsApp a un backend

Los resultados de búsqueda para esta consulta son en su mayoría listados de mercado y envoltorios de API que muestran un parámetro de teléfono y una respuesta de verdadero o falso. Varios de ellos ejecutan comprobaciones a través de una sesión de WhatsApp conectada, por lo que la API deja de responder cuando ese teléfono se desconecta. Pocos explican qué significa la respuesta para el código que la consume, o cómo gestionar los casos en los que no es posible obtener una respuesta.

Para el trabajo de backend, el modelo mental útil es sencillo. Una API de verificación de WhatsApp responde a una pregunta por número: ¿había una cuenta de WhatsApp registrada en este número cuando se ejecutó la comprobación? Esa es una señal de presencia en cuenta para una plataforma. Es una buena entrada para:

• elegir si vale la pena intentar contactar por WhatsApp antes que por otro canal;
• limpiar un campo de teléfono en un CRM o base de datos de clientes potenciales;
• añadir contexto a una cola de revisión de registro o incorporación.

No es una declaración sobre quién posee el número o si aceptó ser contactado. Mantenga sus registros de consentimiento e historial de contacto como entradas separadas, y almacene la fecha de cada comprobación para que el valor pueda actualizarse más tarde.

Cómo llamar a la API de verificación de WhatsApp para un solo número

La llamada de un solo número es una solicitud HTTPS con una respuesta. No hay ningún trabajo que crear, nada que consultar y ninguna URL de devolución de llamada que exponer.

1. Normalizar a E.164. Envíe el número con un signo más, el código de país y el número nacional, siguiendo el ITU-T E.164. Elimine espacios, corchetes y prefijos troncales nacionales. Un número móvil alemán escrito localmente como 0151 2345 6789 se convierte en +4915123456789. La biblioteca libphonenumber de Google analiza la entrada sin procesar con una región predeterminada y es más segura que las reglas de cadena escritas a mano.
2. Elegir la verificación. Establezca service_type en ws, ws_avatar o ws_business dependiendo de la decisión que impulsará el resultado.
3. Autenticar desde el servidor. Envíe la clave en el encabezado X-API-Key. Cárguela desde un almacén de secretos o configuración de entorno, y nunca la coloque en código de navegador, un paquete de aplicación móvil o un repositorio público.
4. Enviar POST /api/v1/check. El resultado para ese número llega en la respuesta a la misma solicitud.
5. Ramificar según el resultado. Un resultado completado lleva la respuesta para la verificación seleccionada. Un código de negocio distinto de cero significa que la verificación no pudo decidirse por el momento.

Construya el cuerpo de la solicitud y el análisis de respuesta a partir de la documentación actual de la API de WA Lookup. Las cargas útiles de los ejemplos de otros proveedores difieren, y copiarlas es una fuente común de errores de integración.

Elección del tipo de verificación: ws, ws_avatar o ws_business

El valor de service_type decide qué señal regresa. Elija la verificación más específica que responda a la pregunta que su código está haciendo, porque cada verificación completada se cobra tanto si la respuesta es Registrado como si es No registrado.

ws

La Verificación de registro en WhatsApp. Indica al backend si el número enviado tenía una cuenta de WhatsApp registrada en el momento de la comprobación. Este es el valor predeterminado para decisiones de canal, limpieza de listas y revisión de registros.

ws_avatar

La Verificación de avatar de WhatsApp. Junto con el registro, informa si hay una foto de perfil disponible y, donde la hay, un enlace a ella. El enlace puede ser una cadena vacía. Úselo para enriquecer registros de contacto o para dar a un revisor humano más contexto. Una foto faltante no dice nada sobre si el número está registrado.

ws_business

La Verificación de cuenta de WhatsApp Business. Junto con el registro, informa si la cuenta es una cuenta de WhatsApp Business, el tipo de cuenta creado con la WhatsApp Business app o plataforma de negocios. Los equipos de ventas lo usan para separar cuentas de empresa de las estándar. Describe solo el tipo de cuenta y no es una verificación de una empresa legal.

Comprobación de hasta 100 números con el endpoint de verificación por lotes

Cuando un backend ya tiene un grupo de números, como una importación nocturna o un envío de formulario con varios contactos, POST /api/v1/batch-check envía hasta 100 números en una única solicitud síncrona. Todo el lote regresa en la respuesta a esa solicitud, o la solicitud falla en su conjunto.

Ese comportamiento da forma al código cliente:

• Dividir listas grandes. Divida la entrada en grupos de 100 o menos y envíelos uno tras otro o con un número pequeño y controlado en vuelo.
• Tratar una solicitud fallida como una unidad. Si la solicitud de lote falla, reintente ese fragmento; no marque sus números con ningún resultado.
• Leer resultados por número. Dentro de un lote exitoso, cada número tiene su propio resultado completado o indeterminado, por lo que la lógica de ramificación del flujo de un solo número se aplica a cada entrada.
• Deduplicar primero. Normalizar antes de dividir a menudo revela duplicados escritos en diferentes formatos locales; comprobar cada número una vez mantiene el gasto predecible.

El endpoint de lote sigue siendo un flujo de misma respuesta. Es la herramienta adecuada para decenas o unos pocos cientos de números manejados por código de aplicación, no para un archivo con una lista muy grande.

Gestión de comprobaciones indeterminadas y errores de solicitud

El error de integración más costoso es escribir "No registrado" en una base de datos cuando la comprobación nunca llegó a una decisión. Un resultado completado de No registrado es una respuesta real. Un código de negocio distinto de cero no es una respuesta en absoluto.

Un patrón de ramificación práctico:

Use retroceso exponencial para reintentos y limite el número de intentos, para que un problema temporal no se convierta en una ráfaga de llamadas repetidas. Mantenga los números indeterminados en un estado separado como "pendiente de re-comprobación", lo que permite que los informes los distingan de los resultados decididos.

Ejecución de la integración en producción

Algunos hábitos operativos hacen que una integración de verificación sea más fácil de mantener:

• Respetar los controles documentados. La documentación actual de la API describe los controles de concurrencia y tiempo de espera por usuario. Ajuste el número de solicitudes en vuelo a esos controles y lea la documentación nuevamente al escalar, en lugar de asumir una asignación fija por minuto.
• Vigilar el saldo de la cuenta. Un saldo de cuenta cubre el panel, la API REST y el servidor MCP, por lo que un trabajo grande de API y las comprobaciones manuales del panel consumen del mismo fondo. Verifique el saldo en el panel antes de una ejecución grande.
• Registrar sin filtrar. Registre los resultados de las solicitudes y los códigos de error, pero enmascare los números de teléfono en los registros generales de la aplicación y nunca registre la clave API.
• Rotar claves. El panel gestiona las claves API; rote una clave si puede haber estado expuesta y actualice el almacén de secretos en un solo paso.
• Registrar contexto. Almacene qué verificación se ejecutó y cuándo. Un resultado de hace meses describe el número en ese momento, no hoy.

Los Términos de servicio de WhatsApp restringen el acceso automatizado o no autorizado a sus servicios, lo cual es una razón por la que los equipos se alejan de los scripts que impulsan una sesión personal y se dirigen a una API alojada con su propia clave.

Cuándo un trabajo de archivo se ajusta mejor que la API

Para una lista muy grande, un trabajo masivo asíncrono es la mejor opción: suba un archivo TXT o CSV con un número por línea, espere el procesamiento y luego descargue un result.csv. Los trabajos masivos usan POST /api/v1/bulk-tasks para enviar y GET /api/v1/bulk-tasks/{id} para seguir el progreso, y se aplican los límites por producto según se describe en la documentación de la API. El archivo debe contener números esencialmente de un país, y los servicios masivos no cubren números de China continental, Hong Kong o Macao. El saldo masivo se reserva al enviar, y la parte no utilizada se devuelve después del procesamiento.

Para la mayoría de las funciones de backend que reaccionan a una acción del usuario o una pequeña importación, las llamadas síncronas de verificación individual y por lotes siguen siendo la opción más sencilla.

Preguntas frecuentes

¿Cómo pueden los equipos probar una API de verificación de WhatsApp antes de integrarla en producción?

Comience con un puñado de números cuyo resultado esperado el equipo ya conozca, como teléfonos de la empresa, y llame al endpoint de un solo número desde un entorno de pruebas. Las cuentas nuevas elegibles reciben automáticamente 100 comprobaciones gratuitas una vez después del registro, lo cual suele ser suficiente para ejercitar las rutas de Registrado, No registrado y reintento en el código cliente.

¿Qué debe hacer un backend cuando un número regresa como indeterminado?

Deje el campo de resultado vacío, registre el código de negocio y la hora, y coloque el número en una cola de reintento con retroceso. Escribir un valor de No registrado para una comprobación indeterminada corrompe los datos de la lista y conduce a decisiones de canal incorrectas más adelante.

¿El endpoint de verificación por lotes funciona de manera diferente a una carga de archivo?

Sí. El endpoint de verificación por lotes devuelve hasta 100 resultados en la respuesta a la misma solicitud. Una carga de archivo crea un trabajo masivo asíncrono que se procesa en segundo plano, después de lo cual se descarga un result.csv.

¿Qué tipo de verificación debe usar una integración de CRM de forma predeterminada?

La Verificación de registro en WhatsApp, ws, cubre la mayoría de las decisiones de canal y calidad de datos. Añada ws_avatar o ws_business solo cuando un campo en el CRM realmente use la disponibilidad de avatar o el tipo de cuenta, ya que cada verificación completada se cobra.

Más información

Elija la información del producto que se ajuste al siguiente paso en su flujo de trabajo.

• Ver la documentación del producto →
• Hablar con el equipo →