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

# Gestione delle istanze

> Crea, connetti e gestisci le istanze WhatsApp durante il loro intero ciclo di vita.

# Gestione delle istanze

Un'**istanza** rappresenta un singolo numero WhatsApp collegato a Wappfy. Ogni istanza attraversa un ciclo di vita: creazione, connessione, scansione QR, utilizzo e infine disconnessione o eliminazione.

## Tipi di istanza

Wappfy supporta due provider:

| Tipo        | Descrizione                                                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `waha`      | API WhatsApp Web self-hosted tramite WAHA Plus. Supporto completo di tutte le funzionalita, inclusi gruppi, etichette e contatti. |
| `cloud_api` | API ufficiale WhatsApp Business Cloud di Meta. Richiede un account Meta Business.                                                 |

## Valori di stato dell'istanza

Durante il suo ciclo di vita, un'istanza attraversa i seguenti stati:

| Stato          | Descrizione                                                                   |
| -------------- | ----------------------------------------------------------------------------- |
| `created`      | Il record dell'istanza esiste ma non e ancora stato avviato.                  |
| `starting`     | L'istanza si sta avviando e inizializzando la sessione WhatsApp.              |
| `scan_qr`      | L'istanza e in attesa della scansione del codice QR con il telefono.          |
| `connected`    | La sessione WhatsApp e attiva e pronta per inviare/ricevere messaggi.         |
| `disconnected` | La sessione e stata fermata o ha perso la connessione. Puo essere riconnessa. |
| `failed`       | L'istanza ha riscontrato un errore durante l'avvio o la connessione.          |

## Panoramica del ciclo di vita

```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
```

***

## Creare un'istanza

Crea una nuova istanza WhatsApp associata al tuo account.

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

**Risposta:**

```json theme={null}
{
  "data": {
    "id": "inst_abc123",
    "name": "My WhatsApp",
    "type": "waha",
    "status": "created",
    "created_at": "2026-02-10T12:00:00Z"
  }
}
```

***

## Connettere un'istanza

Avvia la sessione WhatsApp. L'istanza passera allo stato `starting` e poi 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"
```

**Risposta:**

```json theme={null}
{
  "data": {
    "id": "inst_abc123",
    "status": "starting"
  }
}
```

***

## Ottenere il codice QR

Quando l'istanza raggiunge lo stato `scan_qr`, recupera il codice QR da scansionare con il 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>

**Risposta:**

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

<Note>
  Il codice QR scade dopo circa 60 secondi. Se scade prima della scansione, richiama l'endpoint per ottenere un nuovo codice.
</Note>

Apri l'immagine del codice QR e scansionala con **WhatsApp > Dispositivi collegati > Collega un dispositivo** sul tuo telefono. Una volta scansionato, lo stato dell'istanza cambiera in `connected`.

***

## Verificare lo stato dell'istanza

Interroga l'endpoint di stato per sapere quando l'istanza e pronta.

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

**Risposta:**

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

<Tip>
  Invece di interrogare periodicamente, configura un [webhook](/it/guides/webhooks) per gli eventi `instance.connected` e `instance.qr` per ricevere notifiche in tempo reale.
</Tip>

***

## Elencare tutte le istanze

Recupera tutte le istanze del tuo account.

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

**Risposta:**

```json theme={null}
{
  "data": [
    {
      "id": "inst_abc123",
      "name": "My WhatsApp",
      "type": "waha",
      "status": "connected"
    },
    {
      "id": "inst_def456",
      "name": "Support Line",
      "type": "waha",
      "status": "disconnected"
    }
  ]
}
```

***

## Disconnettere un'istanza

Ferma la sessione WhatsApp senza eliminare l'istanza. Puoi riconnetterti in seguito.

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

***

## Riavviare un'istanza

Riavvia la sessione WhatsApp. Utile se l'istanza si trova in stato `failed` o si comporta in modo anomalo.

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

<Note>
  Il riavvio preserva la sessione WhatsApp collegata. Non sara necessario scansionare nuovamente il codice QR.
</Note>

***

## Disconnettersi da un'istanza

Effettua il logout completo da WhatsApp. Questo scollega il telefono dalla sessione. Sara necessario scansionare nuovamente il codice QR per riconnettersi.

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

<Warning>
  Il logout rimuove completamente il collegamento WhatsApp. A differenza della disconnessione, **devi** scansionare un nuovo codice QR per utilizzare nuovamente questa istanza.
</Warning>

***

## Eliminare un'istanza

Elimina definitivamente un'istanza e tutti i dati associati.

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

<Warning>
  Questa azione e irreversibile. Tutti i messaggi, i webhook e le configurazioni associati a questa istanza verranno eliminati definitivamente.
</Warning>

***

## Esempio completo del ciclo di vita

Ecco un esempio completo che crea un'istanza, la connette e recupera il codice QR:

```bash theme={null}
# 1. Create the instance
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. Connect the instance
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: YOUR_API_KEY"

# 3. Wait a moment, then fetch the QR code
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. Poll for connected status
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
```

***

## Gestione degli errori

| Codice di stato | Descrizione                                                                    |
| --------------- | ------------------------------------------------------------------------------ |
| `404`           | Istanza non trovata o non appartiene al tuo account.                           |
| `409`           | L'istanza e gia nello stato richiesto (es. gia connessa).                      |
| `422`           | Corpo della richiesta non valido (es. `name` mancante o `type` non valido).    |
| `429`           | Limite di frequenza superato. Consulta [Limiti di frequenza](/it/rate-limits). |