> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wappfy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestion de instancias

> Crea, conecta y gestiona instancias de WhatsApp a lo largo de todo su ciclo de vida.

# 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:

| Tipo        | Descripcion                                                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `waha`      | API de WhatsApp Web autoalojada mediante WAHA Plus. Soporte completo de funcionalidades incluyendo grupos, etiquetas y contactos. |
| `cloud_api` | API 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:

| Estado         | Descripcion                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `created`      | El registro de la instancia existe pero aun no ha sido iniciada.         |
| `starting`     | La instancia esta iniciandose y configurando la sesion de WhatsApp.      |
| `scan_qr`      | La instancia esta esperando a que escanees el codigo QR con tu telefono. |
| `connected`    | La sesion de WhatsApp esta activa y lista para enviar/recibir mensajes.  |
| `disconnected` | La sesion fue detenida o perdio la conexion. Puede reconectarse.         |
| `failed`       | La instancia encontro un error durante el inicio o la conexion.          |

## Vista general del ciclo de vida

```mermaid theme={null}
graph LR
    A[created] --> B[starting]
    B --> C[scan_qr]
    C --> D[connected]
    D --> E[disconnected]
    E --> B
    B --> F[failed]
    F --> B
```

***

## Crear una instancia

Crea una nueva instancia de WhatsApp asociada a tu cuenta.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.wappfy.io/api/instances", {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "My WhatsApp",
      type: "waha",
    }),
  });

  const instance = await response.json();
  console.log(instance.data.id); // use this ID for all subsequent calls
  ```
</CodeGroup>

**Respuesta:**

```json theme={null}
{
  "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`.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/connect \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Respuesta:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/qr \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/qr",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  // data.qr contains a base64-encoded QR code image
  ```
</CodeGroup>

**Respuesta:**

```json theme={null}
{
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}
```

<Note>
  El codigo QR expira aproximadamente despues de 60 segundos. Si expira antes de escanearlo, llama al endpoint nuevamente para obtener un codigo nuevo.
</Note>

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.

```bash theme={null}
curl https://api.wappfy.io/api/instances/inst_abc123/status \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Respuesta:**

```json theme={null}
{
  "data": {
    "id": "inst_abc123",
    "status": "connected",
    "phone_number": "5511999998888"
  }
}
```

<Tip>
  En lugar de hacer polling, configura un [webhook](/es/guides/webhooks) para los eventos `instance.connected` e `instance.qr` para recibir notificaciones en tiempo real.
</Tip>

***

## Listar todas las instancias

Recupera todas las instancias de tu cuenta.

```bash theme={null}
curl https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Respuesta:**

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/restart \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Note>
  Reiniciar preserva la sesion de WhatsApp vinculada. No necesitaras escanear el codigo QR nuevamente.
</Note>

***

## 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.

```bash theme={null}
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/logout \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Warning>
  Cerrar sesion elimina completamente el vinculo con WhatsApp. A diferencia de desconectar, **debes** escanear un nuevo codigo QR para usar esta instancia de nuevo.
</Warning>

***

## Eliminar una instancia

Elimina permanentemente una instancia y todos sus datos asociados.

```bash theme={null}
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123 \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Warning>
  Esta accion es irreversible. Todos los mensajes, webhooks y configuracion asociados a esta instancia seran eliminados permanentemente.
</Warning>

***

## Ejemplo de ciclo de vida completo

Aqui tienes un ejemplo completo que crea una instancia, la conecta y consulta el codigo QR:

```bash theme={null}
# 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 estado | Descripcion                                                                 |
| ---------------- | --------------------------------------------------------------------------- |
| `404`            | Instancia no encontrada o no pertenece a tu cuenta.                         |
| `409`            | La instancia ya esta en el estado solicitado (por ejemplo, ya conectada).   |
| `422`            | Cuerpo de solicitud invalido (por ejemplo, falta `name` o `type` invalido). |
| `429`            | Limite de tasa excedido. Consulta [Limites de tasa](/es/rate-limits).       |