Apariencia
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-Afteryerror.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" } }state | Qué ve el contacto |
|---|---|
typing | "escribiendo…" |
recording | "grabando audio…" |
paused | Nada (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
}
}namees 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);nullsi nunca han hablado.businesstraecategory,description,email,websiteyaddressde 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
| Estado | Código | Cuándo |
|---|---|---|
| 409 | INSTANCE_NOT_CONNECTED | La instancia no está conectada. |
| 422 | VALIDATION_FAILED | Un número no es válido (details.fields dice cuál) o state no existe. |
| 404 | PICTURE_NOT_AVAILABLE | Foto: el número no tiene foto, la oculta o no tiene WhatsApp. |
| 422 | RECIPIENT_NOT_ON_WHATSAPP | Presencia: el número no tiene WhatsApp. |
| 429 | CONTACT_CHECK_LIMIT | Se agotó el límite diario de verificaciones de la instancia. |
| 502 | PROVIDER_ERROR | WhatsApp no respondió; reintenta en un momento. |