El nombre de usuario existe

Comprueba si un nombre de usuario (handle) de WhatsApp existe en WhatsApp y obtén el id de cuenta asociado (wid).

POST https://api.getincloud.ai/v1/verify/username

Comprueba si un nombre de usuario (handle) de WhatsApp existe en WhatsApp y obtén el id de cuenta asociado (wid). La comprobación se realiza en tiempo real contra WhatsApp.

Puedes comprobar un nombre de usuario a la vez. Para comprobar varios nombres de usuario, puedes enviar varias solicitudes HTTPS a la API.

La comprobación del nombre de usuario se realiza en tiempo real, por lo que la sesión de tu número de WhatsApp debe estar en línea y sincronizada; de lo contrario, la API devolverá un error 503 - Not Available.

Importante: algunos nombres de usuario requieren una clave de 4 dígitos antes de que WhatsApp revele el id de cuenta asociado. Cuando esto ocurre, la respuesta llega con exists: true, keyRequired: true y wid: null. Es un resultado de existencia normal y positivo, y actualmente es el caso habitual durante el despliegue, no un error. Vuelve a enviar la solicitud con el campo key una vez que lo tengas para resolver el wid.

Para la validación del formato del nombre de usuario sin comprobar su existencia en WhatsApp, consulta el endpoint de la API [Validate/Username](#operation/validateUsername).

Nota de facturación: cada comprobación que devuelve un 200 (exists: true o false, con o sin keyRequired) consume una unidad de la misma cuota mensual de comprobación de números que usa [Numbers/Exists](#operation/verifyNumber). La verificación de nombres de usuario y la de teléfonos comparten una sola cuota, no se cuentan por separado. La cuota se aplica de forma estricta, no solo se contabiliza: una vez agotada, la solicitud se rechaza con un 429 antes de realizar cualquier comprobación contra WhatsApp. Una solicitud rechazada por la validación local previa de formato, rechazada o limitada con un 429, o que falla con un 503 (ningún dispositivo candidato pudo completar la comprobación) no consume nada. Las comprobaciones de solo formato no tienen costo en ningún caso; consulta [Validate/Username](#operation/validateUsername) para ellas.

El campo errorCode en una respuesta 400 es un código que puedes usar para identificar el error. Hay tres posibles resultados. Una solicitud rechazada por la validación local previa de formato (el caso habitual) devuelve error:username:<CODE>, donde <CODE> es exactamente el valor de error documentado en [Validate/Username](#operation/validateUsername): INVALID_CHARACTER, INVALID_LENGTH, INVALID_NO_LETTERS, INVALID_PERIODS, INVALID_WWW_PREFIX, INVALID_DOMAIN_SUFFIX o INVALID_WORD. En el caso menos frecuente en que nuestra validación local previa discrepe del validador en vivo de WhatsApp, el 400 se transmite desde WhatsApp como error:usernameExists:<code>, donde <code> es uno de empty, length, invalid_character, invalid_no_letters, invalid_periods, invalid_www_prefix, invalid_domain_suffix o invalid_word (en minúsculas). En tercer lugar, una key mal formada (que no tenga exactamente 4 dígitos) falla la validación antes de cualquier llamada a WhatsApp y devuelve un error:generic genérico sin un código más específico; envía una key bien formada para evitarlo. Consulta el conjunto exacto en el esquema de respuesta 400 más abajo. Un tiempo de espera agotado o la falta de disponibilidad por parte de WhatsApp nunca es un 400: se manifiesta como un 503 con un errorCode genérico, ya que ningún dispositivo candidato pudo completar la comprobación.

Prueba este endpoint en el probador de API en vivo

>¿Necesitas ayuda? Explora todos los tutoriales, más de 100 ejemplos de casos de uso y juega con el probador de API en vivo con ejemplos de código listos para usar en más de 15 lenguajes de programación, incluidos JavaScript/Node.js, PHP, Python, C#, Java, Ruby, Swift, Kotlin, Powershell, cURL y más.

Autenticación

Envía tu API key en el encabezado Token en cada petición.

Cuerpo de la petición

Respuestas

// This code example requires you to have installed curl package
// Installation instructions here: https://curl.haxx.se/download.html

// Validate if a username exists in WhatsApp
curl --request POST \
  --url https://api.getincloud.ai/v1/verify/username \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"username":"johndoe"}'


// Resolve a username that previously required a key
curl --request POST \
  --url https://api.getincloud.ai/v1/verify/username \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"username":"johndoe","key":"1234"}'