Saltar al contenido principal

​
Gestion de instancias

Una instancia representa un unico numero de WhatsApp conectado a Wappfy. Cada instancia pasa por un ciclo de vida: crear, conectar, escanear QR, usar y eventualmente desconectar o eliminar.

​
Tipos de instancia

Wappfy soporta dos proveedores:
TipoDescripcion
wahaAPI de WhatsApp Web autoalojada mediante WAHA Plus. Soporte completo de funcionalidades incluyendo grupos, etiquetas y contactos.
cloud_apiAPI oficial de WhatsApp Business Cloud de Meta. Requiere una cuenta Meta Business.

​
Valores de estado de la instancia

A lo largo de su ciclo de vida, una instancia transiciona entre estos estados:
EstadoDescripcion
createdEl registro de la instancia existe pero aun no ha sido iniciada.
startingLa instancia esta iniciandose y configurando la sesion de WhatsApp.
scan_qrLa instancia esta esperando a que escanees el codigo QR con tu telefono.
connectedLa sesion de WhatsApp esta activa y lista para enviar/recibir mensajes.
disconnectedLa sesion fue detenida o perdio la conexion. Puede reconectarse.
failedLa instancia encontro un error durante el inicio o la conexion.

​
Vista general del ciclo de vida

​
Crear una instancia

Crea una nueva instancia de WhatsApp asociada a tu cuenta. 
curl -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My WhatsApp",
    "type": "waha"
  }'
Respuesta: 
{
  "data": {
    "id": "inst_abc123",
    "name": "My WhatsApp",
    "type": "waha",
    "status": "created",
    "created_at": "2026-02-10T12:00:00Z"
  }
}

​
Conectar una instancia

Inicia la sesion de WhatsApp. La instancia pasara al estado starting y luego a scan_qr. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/connect \
  -H "X-Api-Key: YOUR_API_KEY"
Respuesta: 
{
  "data": {
    "id": "inst_abc123",
    "status": "starting"
  }
}

​
Obtener el codigo QR

Una vez que la instancia alcance el estado scan_qr, recupera el codigo QR para escanearlo con tu telefono. 
curl https://api.wappfy.io/api/instances/inst_abc123/qr \
  -H "X-Api-Key: YOUR_API_KEY"
Respuesta: 
{
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}
El codigo QR expira aproximadamente despues de 60 segundos. Si expira antes de escanearlo, llama al endpoint nuevamente para obtener un codigo nuevo.
Abre la imagen del codigo QR y escaneala con WhatsApp > Dispositivos vinculados > Vincular un dispositivo en tu telefono. Una vez escaneado, el estado de la instancia cambiara a connected.

​
Verificar el estado de la instancia

Consulta el endpoint de estado para saber cuando la instancia esta lista. 
curl https://api.wappfy.io/api/instances/inst_abc123/status \
  -H "X-Api-Key: YOUR_API_KEY"
Respuesta: 
{
  "data": {
    "id": "inst_abc123",
    "status": "connected",
    "phone_number": "5511999998888"
  }
}
En lugar de hacer polling, configura un webhook para los eventos instance.connected e instance.qr para recibir notificaciones en tiempo real.

​
Listar todas las instancias

Recupera todas las instancias de tu cuenta. 
curl https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY"
Respuesta: 
{
  "data": [
    {
      "id": "inst_abc123",
      "name": "My WhatsApp",
      "type": "waha",
      "status": "connected"
    },
    {
      "id": "inst_def456",
      "name": "Support Line",
      "type": "waha",
      "status": "disconnected"
    }
  ]
}

​
Desconectar una instancia

Detiene la sesion de WhatsApp sin eliminar la instancia. Puedes reconectar despues. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/disconnect \
  -H "X-Api-Key: YOUR_API_KEY"

​
Reiniciar una instancia

Reinicia la sesion de WhatsApp. Esto es util si la instancia esta en estado failed o se comporta de manera inesperada. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/restart \
  -H "X-Api-Key: YOUR_API_KEY"
Reiniciar preserva la sesion de WhatsApp vinculada. No necesitaras escanear el codigo QR nuevamente.

​
Cerrar sesion de una instancia

Cierra la sesion de WhatsApp completamente. Esto desvincula el telefono de la sesion. Necesitaras escanear el codigo QR nuevamente para reconectar. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/logout \
  -H "X-Api-Key: YOUR_API_KEY"
Cerrar sesion elimina completamente el vinculo con WhatsApp. A diferencia de desconectar, debes escanear un nuevo codigo QR para usar esta instancia de nuevo.

​
Eliminar una instancia

Elimina permanentemente una instancia y todos sus datos asociados. 
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123 \
  -H "X-Api-Key: YOUR_API_KEY"
Esta accion es irreversible. Todos los mensajes, webhooks y configuracion asociados a esta instancia seran eliminados permanentemente.

​
Ejemplo de ciclo de vida completo

Aqui tienes un ejemplo completo que crea una instancia, la conecta y consulta el codigo QR: 
# 1. Crear la instancia
INSTANCE=$(curl -s -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "type": "waha"}')

INSTANCE_ID=$(echo $INSTANCE | jq -r '.data.id')
echo "Created instance: $INSTANCE_ID"

# 2. Conectar la instancia
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: YOUR_API_KEY"

# 3. Esperar un momento, luego obtener el codigo QR
sleep 3
QR=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/qr" \
  -H "X-Api-Key: YOUR_API_KEY")

echo $QR | jq -r '.data.qr' > qr-code.png
echo "QR code saved to qr-code.png — scan it with your phone"

# 4. Consultar el estado hasta que este conectado
while true; do
  STATUS=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/status" \
    -H "X-Api-Key: YOUR_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "connected" ]; then
    echo "Instance is connected and ready!"
    break
  fi
  sleep 2
done

​
Manejo de errores

Codigo de estadoDescripcion
404Instancia no encontrada o no pertenece a tu cuenta.
409La instancia ya esta en el estado solicitado (por ejemplo, ya conectada).
422Cuerpo de solicitud invalido (por ejemplo, falta name o type invalido).
429Limite de tasa excedido. Consulta Limites de tasa.