Ir al contenido

Verificar números, perfil y "escribiendo…" ​

Acciones sobre una instancia conectada. Ninguna cuenta como mensaje ni genera webhooks. Todas necesitan el scope messages:send.

Verificar si un número tiene WhatsApp ​

Antes de escribir a una lista de números, pregunta cuáles tienen WhatsApp. Así no envías mensajes que van a fallar y cuidas la reputación de tu número.

bash
curl -X POST "https://zappio.cloud/api/v1/instances/ins_.../contacts/check" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["+52 1 55 0000 0000", "5255000012345"]}'
json
{
  "data": {
    "results": [
      { "phone": "5215500000000", "exists": true },
      { "phone": "5255000012345", "exists": false }
    ],
    "daily_limit": 30,
    "remaining_today": 28
  }
}
  • Hasta 50 números por llamada, en formato internacional (código de país + número). Los repetidos se responden una vez.
  • Las respuestas vienen en el mismo orden, con cada número normalizado a dígitos.
  • Cada número cuenta contra el límite diario de la instancia: 30 en la prueba y 1000 en el plan de pago. Se reinicia a las 00:00 UTC.
  • Un lote que no cabe en lo que queda del día se rechaza completo con 429 CONTACT_CHECK_LIMIT, Retry-After y error.details.remaining_today. Lo que WhatsApp no alcanzó a responder no se cuenta.

Mostrar "escribiendo…" o "grabando audio…" ​

bash
curl -X POST "https://zappio.cloud/api/v1/instances/ins_.../presence" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+52 1 55 0000 0000", "state": "typing"}'
json
{ "data": { "state": "typing" } }
stateQué ve el contacto
typing"escribiendo…"
recording"grabando audio…"
pausedNada (lo quita)

Usa phone para un chat directo o group (grp_...) para un grupo, nunca los dos. WhatsApp lo quita solo a los pocos segundos: si sigues escribiendo, vuelve a enviarlo. Un patrón común es mandar typing, esperar 2 o 3 segundos y luego enviar el mensaje.

Perfil y foto de un contacto ​

Lo que WhatsApp muestra de un número: si tiene WhatsApp, su "info", su perfil de negocio (si es una cuenta Business) y si tiene foto. Lo que el contacto oculta por privacidad sale null.

bash
curl "https://zappio.cloud/api/v1/instances/ins_.../contacts/5215500000000" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"
json
{
  "data": {
    "phone": "5215500000000",
    "exists": true,
    "name": "Ana López",
    "about": "Disponible",
    "about_updated_at": "2026-10-01T12:00:00.000Z",
    "business": null,
    "picture_url": "https://zappio.cloud/api/v1/instances/ins_.../contacts/5215500000000/picture",
    "daily_limit": 30,
    "remaining_today": 27
  }
}
  • name es el nombre que el contacto se puso en WhatsApp, tal como ZAPPIO lo vio en un chat con tu número (WhatsApp no lo da por consulta); null si nunca han hablado.
  • business trae category, description, email, website y address de las cuentas WhatsApp Business.
  • Cada consulta descuenta 1 del mismo límite diario de verificaciones.

La foto se pide con picture_url (la misma API key) y pasa por ZAPPIO: nunca recibes un enlace de WhatsApp, que caduca. ZAPPIO la guarda 24 horas; mientras tanto pedirla otra vez no consulta a WhatsApp ni descuenta del límite. Si el número no tiene foto, la oculta o no tiene WhatsApp, responde 404 PICTURE_NOT_AVAILABLE.

bash
curl -o avatar.jpg "https://zappio.cloud/api/v1/instances/ins_.../contacts/5215500000000/picture" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"

Errores ​

EstadoCódigoCuándo
409INSTANCE_NOT_CONNECTEDLa instancia no está conectada.
422VALIDATION_FAILEDUn número no es válido (details.fields dice cuál) o state no existe.
404PICTURE_NOT_AVAILABLEFoto: el número no tiene foto, la oculta o no tiene WhatsApp.
422RECIPIENT_NOT_ON_WHATSAPPPresencia: el número no tiene WhatsApp.
429CONTACT_CHECK_LIMITSe agotó el límite diario de verificaciones de la instancia.
502PROVIDER_ERRORWhatsApp no respondió; reintenta en un momento.