Instancias y conexión

Una instancia es un número de WhatsApp conectado a ZAPPIO. Es lo que usas para enviar y recibir mensajes: cada mensaje se envía desde una instancia (instance en la petición) y cada evento dice a qué instancia pertenece.

Estados

Estado	Significa	Qué hacer
created	Existe, todavía sin conectar.	Conéctala.
connecting	Se está estableciendo la conexión.	Espera unos segundos.
qr_required	Espera que escanees un código QR.	Escanéalo con WhatsApp.
connected	Conectada; ya puede enviar y recibir.	—
reconnecting	Se cayó la conexión y ZAPPIO intenta recuperarla.	Nada: es automático.
disconnected	No está conectada en este momento.	Vuelve a conectar.
logged_out	WhatsApp desvinculó el dispositivo.	Conecta de nuevo y escanea un QR nuevo.
error	Algo falló; last_error dice qué.	Reintenta la conexión.

Conectar un número

Desde el panel

Instancias → Agregar instancia → ponle un nombre → Crear. Abre la instancia, elige Conectar WhatsApp y escanea el QR: en WhatsApp, Dispositivos vinculados → Vincular un dispositivo. Cuando el estado sea Conectado, ya puedes enviar mensajes.

Por API

Necesitas una clave con instances:write (y instances:read para consultar).

# 1. Crear la instancia
curl -X POST "https://zappio.cloud/api/v1/instances" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Ventas"}'

# 2. Iniciar la conexión: responde 202 y el estado pasa a connecting y luego a qr_required
curl -X POST "https://zappio.cloud/api/v1/instances/$ZAPPIO_INSTANCE/connect" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"

# 3. Obtener el QR mientras el estado sea qr_required (SVG)
curl "https://zappio.cloud/api/v1/instances/$ZAPPIO_INSTANCE/qr" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"

El QR rota: si lo muestras en tu propia aplicación, consúltalo de nuevo cada pocos segundos. La persona lo escanea desde WhatsApp, en Dispositivos vinculados. Al terminar, el estado pasa a connected y paired es true.

connect es asíncrono e idempotente: devuelve 202 y la conexión se completa después. Sigue el estado con GET /instances/{instance} o con los eventos instance.* (Webhooks).

Desconectar y cerrar sesión

Operación	Efecto
disconnect	Cierra la conexión pero conserva la vinculación. Al volver a llamar connect se restaura sin QR nuevo.
logout	Desvincula el número. La siguiente conexión necesita un QR nuevo.

Cuando la conexión se interrumpe

Las conexiones pueden interrumpirse. ZAPPIO guarda la sesión e intenta reconectar por su cuenta: verás la instancia en reconnecting y, si lo logra, de vuelta en connected. No tienes que hacer nada.

Hay casos que no se pueden recuperar solos:

• logged_out: WhatsApp cerró la sesión (por ejemplo, desvinculaste el dispositivo desde el teléfono). Hay que conectar de nuevo y escanear un QR.
• error: last_error trae un código en minúsculas (por ejemplo, gateway_unavailable). Reintenta connect.

Para enterarte sin consultar, suscríbete a instance.connected, instance.disconnected, instance.qr_required e instance.error (Eventos).

Mientras una instancia no esté conectada, enviar un mensaje responde 409 INSTANCE_NOT_CONNECTED.

Límites

Tu plan define cuántas instancias puedes tener (la prueba incluye 1). Al llegar al límite, crear otra responde 403 INSTANCE_LIMIT_REACHED. Detalles en Prueba y planes.