Instanzen verwalten

Eine Instanz repraesentiert eine einzelne WhatsApp-Nummer, die mit Wappfy verbunden ist. Jede Instanz durchlaeuft einen Lebenszyklus: Erstellen, Verbinden, QR scannen, Nutzen und schliesslich Trennen oder Loeschen.

Instanztypen

Wappfy unterstuetzt zwei Anbieter:

Typ	Beschreibung
`waha`	Selbstgehostete WhatsApp Web API ueber WAHA Plus. Voller Funktionsumfang inklusive Gruppen, Labels und Kontakte.
`cloud_api`	Metas offizielle WhatsApp Business Cloud API. Erfordert ein Meta-Business-Konto.

Instanz-Statuswerte

Waehrend ihres Lebenszyklus durchlaeuft eine Instanz folgende Status:

Status	Beschreibung
`created`	Instanzdatensatz existiert, wurde aber noch nicht gestartet.
`starting`	Instanz wird hochgefahren und initialisiert die WhatsApp-Sitzung.
`scan_qr`	Instanz wartet darauf, dass Sie den QR-Code mit Ihrem Telefon scannen.
`connected`	WhatsApp-Sitzung ist aktiv und bereit zum Senden/Empfangen von Nachrichten.
`disconnected`	Sitzung wurde gestoppt oder die Verbindung wurde unterbrochen. Kann erneut verbunden werden.
`failed`	Instanz ist beim Start oder der Verbindung auf einen Fehler gestossen.

Lebenszyklus-Uebersicht

Instanz erstellen

Erstellen Sie eine neue WhatsApp-Instanz, die mit Ihrem Konto verknuepft ist.

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

Antwort:

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

Instanz verbinden

Starten Sie die WhatsApp-Sitzung. Die Instanz wechselt in den Status starting und anschliessend in scan_qr.

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

Antwort:

{
  "data": {
    "id": "inst_abc123",
    "status": "starting"
  }
}

QR-Code abrufen

Sobald die Instanz den Status scan_qr erreicht hat, koennen Sie den QR-Code zum Scannen mit Ihrem Telefon abrufen.

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

Antwort:

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

Der QR-Code laeuft nach etwa 60 Sekunden ab. Wenn er ablaeuft, bevor Sie ihn scannen, rufen Sie den Endpunkt erneut auf, um einen neuen Code zu erhalten.

Oeffnen Sie das QR-Code-Bild und scannen Sie es mit WhatsApp > Verknuepfte Geraete > Geraet verknuepfen auf Ihrem Telefon. Nach dem Scannen wechselt der Instanzstatus zu connected.

Instanzstatus pruefen

Fragen Sie den Status-Endpunkt ab, um zu erfahren, wann die Instanz bereit ist.

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

Antwort:

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

Anstatt zu pollen, richten Sie einen Webhook fuer die Ereignisse instance.connected und instance.qr ein, um in Echtzeit benachrichtigt zu werden.

Alle Instanzen auflisten

Rufen Sie alle Instanzen Ihres Kontos ab.

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

Antwort:

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

Instanz trennen

Stoppen Sie die WhatsApp-Sitzung, ohne die Instanz zu loeschen. Sie koennen sich spaeter erneut verbinden.

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

Instanz neustarten

Starten Sie die WhatsApp-Sitzung neu. Dies ist nuetzlich, wenn sich die Instanz im Status failed befindet oder sich unerwartet verhaelt.

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

Ein Neustart bewahrt die verknuepfte WhatsApp-Sitzung. Sie muessen den QR-Code nicht erneut scannen.

Instanz abmelden

Melden Sie sich vollstaendig von WhatsApp ab. Dadurch wird das Telefon von der Sitzung getrennt. Sie muessen den QR-Code erneut scannen, um sich wieder zu verbinden.

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

Die Abmeldung entfernt die WhatsApp-Verknuepfung vollstaendig. Im Gegensatz zum Trennen muessen Sie einen neuen QR-Code scannen, um diese Instanz wieder zu nutzen.

Instanz loeschen

Loeschen Sie eine Instanz und alle zugehoerigen Daten permanent.

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

Diese Aktion ist unwiderruflich. Alle Nachrichten, Webhooks und Konfigurationen, die mit dieser Instanz verbunden sind, werden permanent geloescht.

Vollstaendiges Lebenszyklus-Beispiel

Hier ist ein vollstaendiges Beispiel, das eine Instanz erstellt, verbindet und den QR-Code abfragt:

# 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

Fehlerbehandlung

Statuscode	Beschreibung
`404`	Instanz nicht gefunden oder gehoert nicht zu Ihrem Konto.
`409`	Instanz befindet sich bereits im angeforderten Status (z.B. bereits verbunden).
`422`	Ungueltiger Anfrageinhalt (z.B. fehlender `name` oder ungueltiger `type`).
`429`	Ratenlimit ueberschritten. Siehe Ratenlimits.

Erste Schritte

Anleitungen

Instanzen verwalten

Instanzen verwalten

Instanztypen

Instanz-Statuswerte

Lebenszyklus-Uebersicht

Instanz erstellen

Instanz verbinden

QR-Code abrufen

Instanzstatus pruefen

Alle Instanzen auflisten

Instanz trennen

Instanz neustarten

Instanz abmelden

Instanz loeschen

Vollstaendiges Lebenszyklus-Beispiel

Fehlerbehandlung

​Instanzen verwalten

​Instanztypen

​Instanz-Statuswerte

​Lebenszyklus-Uebersicht

​Instanz erstellen

​Instanz verbinden

​QR-Code abrufen

​Instanzstatus pruefen

​Alle Instanzen auflisten

​Instanz trennen

​Instanz neustarten

​Instanz abmelden

​Instanz loeschen

​Vollstaendiges Lebenszyklus-Beispiel

​Fehlerbehandlung

Instanzen verwalten

Instanztypen

Instanz-Statuswerte

Lebenszyklus-Uebersicht

Instanz erstellen

Instanz verbinden

QR-Code abrufen

Instanzstatus pruefen

Alle Instanzen auflisten

Instanz trennen

Instanz neustarten

Instanz abmelden

Instanz loeschen

Vollstaendiges Lebenszyklus-Beispiel

Fehlerbehandlung