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

# Instanzen verwalten

> Erstellen, verbinden und verwalten Sie WhatsApp-Instanzen ueber ihren gesamten Lebenszyklus.

# 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

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

***

## Instanz erstellen

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

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

**Antwort:**

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

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

**Antwort:**

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

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

**Antwort:**

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

<Note>
  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.
</Note>

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.

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

**Antwort:**

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

<Tip>
  Anstatt zu pollen, richten Sie einen [Webhook](/de/guides/webhooks) fuer die Ereignisse `instance.connected` und `instance.qr` ein, um in Echtzeit benachrichtigt zu werden.
</Tip>

***

## Alle Instanzen auflisten

Rufen Sie alle Instanzen Ihres Kontos ab.

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

**Antwort:**

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

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

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

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

***

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

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

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

***

## Instanz loeschen

Loeschen Sie eine Instanz und alle zugehoerigen Daten permanent.

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

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

***

## Vollstaendiges Lebenszyklus-Beispiel

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

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

***

## 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](/de/rate-limits).                |