Guía de producto
El tipo de servicio ws_avatar: referencia de solicitud, respuesta y campos
Referencia por campos del tipo de servicio ws_avatar de WA Lookup: el contrato de solicitud síncrona, los campos de respuesta y qué contienen avatar y avatar_url.
WA Lookup expone sus verificaciones de WhatsApp mediante una única llamada síncrona, y el valor de service_type decide qué verificación se ejecuta. Esta es la referencia por campos de la variante ws_avatar.
Para ejecutar una verificación de avatar de WhatsApp con WA Lookup, envíe POST /api/v1/check con la cabecera X-API-Key y un cuerpo JSON {"service_type": "ws_avatar", "identifier": "<E.164 number>"}. La respuesta devuelve los campos estándar de la verificación más un booleano avatar y una cadena avatar_url; avatar_url es una cadena vacía cuando no hay URL disponible.
El contrato de solicitud
WA Lookup documenta una única llamada síncrona, POST /api/v1/check, enviada con la cabecera X-API-Key y Content-Type: application/json. El cuerpo contiene exactamente dos valores: service_type, que selecciona la verificación, e identifier, que debe ser el número de teléfono en formato E.164. Enviar un número en formato local es la causa más habitual de un fallo evitable, así que normalícelo antes de enviarlo.
Los campos de respuesta que siempre recibe
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.
Los dos campos que añade ws_avatar
Elegir service_type=ws_avatar añade un booleano avatar y una cadena avatar_url. El booleano avatar indica si se detectó un avatar. El campo avatar_url está siempre presente en una respuesta ws_avatar correcta y es una cadena vacía cuando no hay URL disponible. Manténgalo separado del booleano avatar, porque los dos campos responden a preguntas distintas.
Todo llega en una sola respuesta
Como la llamada es síncrona, los campos de registro y de avatar se devuelven en la misma respuesta HTTP que la solicitud. No hay ningún identificador de trabajo que almacenar ni ninguna ruta de estado que consultar periódicamente, lo que reduce la integración a una sola llamada y una sola ruta de error. El código escrito para una API de sondeo suele tener una estructura que aquí puede eliminarse sin más.
Preguntas frecuentes
¿Cómo debo tratar avatar_url?
El campo avatar_url está siempre presente en una respuesta ws_avatar correcta. Almacene una cadena vacía como «no hay URL disponible»; no la utilice como sustituto del booleano avatar.
¿Qué formato de número requiere identifier?
E.164. Normalizar antes del envío evita la categoría más habitual de verificaciones fallidas.
¿Necesito una segunda llamada para obtener el estado de registro?
No. ws_avatar devuelve el campo de registro junto con los campos de avatar en la misma respuesta.