Zum Hauptinhalt springen

​
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:
TypBeschreibung
wahaSelbstgehostete WhatsApp Web API ueber WAHA Plus. Voller Funktionsumfang inklusive Gruppen, Labels und Kontakte.
cloud_apiMetas offizielle WhatsApp Business Cloud API. Erfordert ein Meta-Business-Konto.

​
Instanz-Statuswerte

Waehrend ihres Lebenszyklus durchlaeuft eine Instanz folgende Status:
StatusBeschreibung
createdInstanzdatensatz existiert, wurde aber noch nicht gestartet.
startingInstanz wird hochgefahren und initialisiert die WhatsApp-Sitzung.
scan_qrInstanz wartet darauf, dass Sie den QR-Code mit Ihrem Telefon scannen.
connectedWhatsApp-Sitzung ist aktiv und bereit zum Senden/Empfangen von Nachrichten.
disconnectedSitzung wurde gestoppt oder die Verbindung wurde unterbrochen. Kann erneut verbunden werden.
failedInstanz 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"
  }'
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"
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

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