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

Creare un’istanza

Crea una nuova istanza WhatsApp associata al tuo account.

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"
  }'

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

Risposta:

{
  "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.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/connect \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta:

{
  "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.

curl https://api.wappfy.io/api/instances/inst_abc123/qr \
  -H "X-Api-Key: YOUR_API_KEY"

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

Risposta:

{
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Il codice QR scade dopo circa 60 secondi. Se scade prima della scansione, richiama l’endpoint per ottenere un nuovo codice.

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.

curl https://api.wappfy.io/api/instances/inst_abc123/status \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta:

{
  "data": {
    "id": "inst_abc123",
    "status": "connected",
    "phone_number": "5511999998888"
  }
}

Invece di interrogare periodicamente, configura un webhook per gli eventi instance.connected e instance.qr per ricevere notifiche in tempo reale.

Elencare tutte le istanze

Recupera tutte le istanze del tuo account.

curl https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta:

{
  "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.

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.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/restart \
  -H "X-Api-Key: YOUR_API_KEY"

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

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.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/logout \
  -H "X-Api-Key: YOUR_API_KEY"

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

Eliminare un’istanza

Elimina definitivamente un’istanza e tutti i dati associati.

curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123 \
  -H "X-Api-Key: YOUR_API_KEY"

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

Esempio completo del ciclo di vita

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

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

Per Iniziare

Guide

Gestione delle istanze

Gestione delle istanze

Tipi di istanza

Valori di stato dell’istanza

Panoramica del ciclo di vita

Creare un’istanza

Connettere un’istanza

Ottenere il codice QR

Verificare lo stato dell’istanza

Elencare tutte le istanze

Disconnettere un’istanza

Riavviare un’istanza

Disconnettersi da un’istanza

Eliminare un’istanza

Esempio completo del ciclo di vita

Gestione degli errori

​Gestione delle istanze

​Tipi di istanza

​Valori di stato dell’istanza

​Panoramica del ciclo di vita

​Creare un’istanza

​Connettere un’istanza

​Ottenere il codice QR

​Verificare lo stato dell’istanza

​Elencare tutte le istanze

​Disconnettere un’istanza

​Riavviare un’istanza

​Disconnettersi da un’istanza

​Eliminare un’istanza

​Esempio completo del ciclo di vita

​Gestione degli errori

Gestione delle istanze

Tipi di istanza

Valori di stato dell’istanza

Panoramica del ciclo di vita

Creare un’istanza

Connettere un’istanza

Ottenere il codice QR

Verificare lo stato dell’istanza

Elencare tutte le istanze

Disconnettere un’istanza

Riavviare un’istanza

Disconnettersi da un’istanza

Eliminare un’istanza

Esempio completo del ciclo di vita

Gestione degli errori