API de foto de perfil de WhatsApp: Análisis de avatares en tiempo real por número de teléfono

Una guía para desarrolladores sobre las API de fotos de perfil de WhatsApp: qué devuelven las herramientas que solo ofrecen URL, en qué se diferencian las solicitudes de análisis de avatares de WhatsApp de AvatarLookup (tanto individuales en tiempo real como múltiples sincrónicas) y cómo almacenar y reintentar resultados.

Una API de foto de perfil de WhatsApp toma un número de teléfono y devuelve información sobre la foto de perfil pública asociada. Muchas herramientas se limitan a proporcionar una URL de imagen temporal que usted debe descargar e interpretar por su cuenta. El Análisis de avatares de WhatsApp de AvatarLookup devuelve un resultado estructurado: una verificación individual en tiempo real mediante POST /api/v1/check, o una verificación múltiple sincrónica mediante POST /api/v1/batch-check con entre 1 y 100 números por solicitud. Los atributos de apariencia en el resultado son estimaciones algorítmicas. Solo se analizan avatares públicos; por lo tanto, un contacto que limite su foto a sus contactos guardados no mostrará una imagen pública, y un resultado indeterminado debe volver a intentarse más tarde en lugar de interpretarse como un veredicto sobre la cuenta.

Tres tipos de API de foto de perfil de WhatsApp

Los resultados de búsqueda para este término mezclan tres conceptos distintos, y elegir el incorrecto desperdicia tiempo de integración.

La configuración oficial de empresa es para la foto de su propia cuenta, no para buscar otros números. Las herramientas de solo URL devuelven enlaces que suelen caducar, por lo que los equipos terminan descargando, almacenando y etiquetando imágenes ellos mismos. El Análisis de avatares omite el paso de gestión de imágenes y devuelve datos que se ajustan a un registro de contacto. Los tres tipos están limitados por la misma regla: la foto debe ser visible públicamente.

Verificación individual en tiempo real con POST /api/v1/check

Utilice la verificación individual cuando un número necesite una respuesta dentro de un flujo interactivo, como cuando un agente de soporte abre un registro de contacto.

1. Normalice el número. Conviértalo al formato internacional con el código de país, siguiendo la estructura de la ITU-T Recommendation E.164, y elimine espacios, guiones y paréntesis.
2. Envíe una solicitud autenticada a POST /api/v1/check especificando el producto de avatar de WhatsApp y el número. Siga la documentación de la API para el cuerpo de la solicitud exacto; no intente adivinar los nombres de los campos.
3. Lea la respuesta una vez y almacénela con la fecha de verificación y una etiqueta de origen de WhatsApp.
4. Ramifique según el resultado: avatar público encontrado, sin avatar público o indeterminado.

Mantenga la llamada fuera de cualquier ruta de bloqueo en la que el cliente deba esperar. Si la verificación es lenta o indeterminada, el registro debe guardarse de todos modos, dejando los campos de avatar vacíos y marcando que se debe realizar una verificación posterior. Los números de China continental, Hong Kong y Macau solo se admiten mediante verificaciones individuales en tiempo real, por lo que deben dirigirse aquí en lugar de a archivos masivos.

Verificación múltiple sincrónica con POST /api/v1/batch-check

La verificación múltiple gestiona una lista corta en una sola llamada. Cada solicitud acepta de 1 a 100 identificadores de un mismo tipo de producto y devuelve resultados como JSON ordenado, coincidiendo con el orden enviado.

Reglas prácticas para solicitudes múltiples:

• No mezcle productos. Envíe números de WhatsApp en una solicitud y direcciones de Gmail, Yandex o Mail.ru compatibles en otra.
• Confíe en el orden, pero verifique. Los resultados siguen el orden de entrada; aun así, haga coincidir cada resultado con su número de entrada antes de escribir en su base de datos.
• Divida las listas largas. Divida una lista de 350 números en cuatro solicitudes de hasta 100.
• Utilice tareas masivas para archivos grandes. Cuando una lista es mucho mayor, el producto masivo de WhatsApp asíncrono acepta un archivo TXT o CSV y devuelve un CSV para la tarea.

Los equipos no técnicos pueden usar el panel de control, que acepta hasta 500 identificadores y los procesa uno por uno. En cualquier caso, solo WhatsApp y los dominios de correo electrónico compatibles tienen verificaciones en tiempo real y múltiples; Telegram, Viber, MAX, LINE y Zalo son solo para procesamiento masivo.

Gestión de resultados indeterminados y sin avatar

La mayoría de los errores de integración provienen de agrupar diferentes resultados en un solo valor vacío. Manténgalos separados:

• Resultado producido. La respuesta múltiple marca cada elemento donde se produjo un resultado. Esa marca significa que existe un resultado para la solicitud, no que la cuenta de WhatsApp exista.
• Resultado no producido. Esto cubre elementos no válidos, indeterminados o fallidos. No es un veredicto negativo sobre la cuenta o su avatar, por lo que debe programar un reintento posterior en lugar de eliminar el contacto.
• Sin avatar público. Un resultado completado puede mostrar que no hay una imagen pública disponible. La configuración de privacidad de WhatsApp permite a los usuarios mostrar su foto de perfil a Todos, Mis contactos, Mis contactos excepto personas seleccionadas o Nadie, por lo que la ausencia de una imagen pública suele ser simplemente una elección de privacidad.

Escriba cada estado en su propio valor, como público, ninguno o reintentar, y registre el motivo de los reintentos. Un modelo de estado limpio también hace que los informes sean honestos: un recuento en el panel de control de "sin avatar" nunca debe incluir elementos que simplemente fueron indeterminados.

Almacenamiento de resultados como estimaciones

Los atributos de apariencia, como el tipo de imagen, un rango de edad o el color de cabello, describen la imagen, no a la persona detrás del número. Un dibujo animado, una mascota, un logotipo o una foto grupal pueden ser fotos de perfil válidas, y su análisis sigue siendo una respuesta completada.

Un patrón de almacenamiento simple:

Mantenga estos campos fuera de las decisiones de elegibilidad, crédito, contratación o precios, y fuera de cualquier filtrado que trate a las personas de manera diferente según la edad o el género estimados. Un avatar público es una señal de datos de contacto; no verifica la identidad, la propiedad de la cuenta ni el consentimiento para contactar. Establezca un intervalo de revisión, ya que los usuarios cambian sus fotos, y elimine las estimaciones obsoletas según su política de retención habitual.

Preguntas frecuentes

¿Cómo pueden los equipos obtener el archivo de imagen real en lugar de los campos de análisis?

El Análisis de avatares está diseñado para devolver resultados estructurados sobre el avatar público, no para actuar como un descargador de imágenes. Si un flujo de trabajo realmente necesita mostrar imágenes, considere si es necesario para el propósito y cómo se almacenarían y eliminarían los archivos. Muchos flujos de trabajo de datos de contacto solo necesitan saber si existe un avatar público y qué tipo de imagen es, lo cual el análisis ya responde.

¿Cómo deben los desarrolladores reintentar las verificaciones de WhatsApp indeterminadas?

Recopile los números indeterminados en una cola de reintento en lugar de volver a enviarlos inmediatamente en un bucle. Vuelva a verificarlos más tarde en una solicitud individual o múltiple, y limite el número de intentos por número para que un fallo persistente no se ejecute indefinidamente. Después del intento final, mantenga el registro como indeterminado en lugar de convertirlo en sin avatar, ya que esos resultados significan cosas diferentes.

¿Cómo pueden los equipos verificar una imagen que ya poseen en lugar de un número de teléfono?

Utilice el Análisis de perfil de imágenes. Acepta archivos JPEG, PNG, WebP o GIF y se invoca a través del punto de conexión de perfil de imagen documentado con una carga de archivo multipart. Describe la imagen en sí, devolviendo el tipo de imagen y los atributos de apariencia como estimaciones algorítmicas, sin involucrar números de teléfono ni cuentas. Esto es adecuado para imágenes que un cliente cargó directamente, como una foto de perfil enviada a través de un formulario.

Más información

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

• Visite el sitio web del producto →