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

# Zarzadzanie instancjami

> Tworzenie, laczenie i zarzadzanie instancjami WhatsApp przez caly cykl zycia.

# Zarzadzanie instancjami

**Instancja** reprezentuje pojedynczy numer WhatsApp polaczony z Wappfy. Kazda instancja przechodzi przez cykl zycia: utworzenie, polaczenie, skanowanie QR, uzytkowanie, a na koncu rozlaczenie lub usuniecie.

## Typy instancji

Wappfy obsluguje dwoch dostawcow:

| Typ         | Opis                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `waha`      | Samodzielnie hostowane WhatsApp Web API poprzez WAHA Plus. Pelna obsluga funkcji, w tym grup, etykiet i kontaktow. |
| `cloud_api` | Oficjalne WhatsApp Business Cloud API od Meta. Wymaga konta Meta Business.                                         |

## Statusy instancji

W trakcie cyklu zycia instancja przechodzi przez nastepujace statusy:

| Status         | Opis                                                                          |
| -------------- | ----------------------------------------------------------------------------- |
| `created`      | Rekord instancji istnieje, ale nie zostal jeszcze uruchomiony.                |
| `starting`     | Instancja uruchamia sie i inicjalizuje sesje WhatsApp.                        |
| `scan_qr`      | Instancja czeka na zeskanowanie kodu QR telefonem.                            |
| `connected`    | Sesja WhatsApp jest aktywna i gotowa do wysylania/odbierania wiadomosci.      |
| `disconnected` | Sesja zostala zatrzymana lub utracono polaczenie. Mozna ja ponownie polaczyc. |
| `failed`       | Instancja napotkala blad podczas uruchamiania lub laczenia.                   |

## Przeglad cyklu zycia

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

***

## Tworzenie instancji

Utworz nowa instancje WhatsApp przypisana do Twojego konta.

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

**Odpowiedz:**

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

***

## Laczenie instancji

Rozpocznij sesje WhatsApp. Instancja przejdzie do statusu `starting`, a nastepnie do `scan_qr`.

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

**Odpowiedz:**

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

***

## Pobieranie kodu QR

Gdy instancja osiagnie status `scan_qr`, pobierz kod QR do zeskanowania telefonem.

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

**Odpowiedz:**

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

<Note>
  Kod QR wygasa po okolo 60 sekundach. Jesli wygasnie przed zeskanowaniem, wywolaj endpoint ponownie, aby uzyskac nowy kod.
</Note>

Otworz obraz kodu QR i zeskanuj go za pomoca **WhatsApp > Polaczone urzadzenia > Polacz urzadzenie** na telefonie. Po zeskanowaniu status instancji zmieni sie na `connected`.

***

## Sprawdzanie statusu instancji

Odpytuj endpoint statusu, aby wiedziec, kiedy instancja jest gotowa.

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

**Odpowiedz:**

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

<Tip>
  Zamiast odpytywac, skonfiguruj [webhook](/pl/guides/webhooks) dla zdarzen `instance.connected` i `instance.qr`, aby otrzymywac powiadomienia w czasie rzeczywistym.
</Tip>

***

## Lista wszystkich instancji

Pobierz wszystkie instancje dla Twojego konta.

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

**Odpowiedz:**

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

***

## Rozlaczanie instancji

Zatrzymaj sesje WhatsApp bez usuwania instancji. Mozesz polaczyc sie ponownie pozniej.

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

***

## Restartowanie instancji

Zrestartuj sesje WhatsApp. Jest to przydatne, gdy instancja jest w stanie `failed` lub zachowuje sie nieoczekiwanie.

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

<Note>
  Restartowanie zachowuje polaczona sesje WhatsApp. Nie bedzie konieczne ponowne skanowanie kodu QR.
</Note>

***

## Wylogowanie instancji

Wyloguj sie calkowicie z WhatsApp. Spowoduje to odlaczenie telefonu od sesji. Aby ponownie polaczyc, konieczne bedzie zeskanowanie kodu QR.

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

<Warning>
  Wylogowanie calkowicie usuwa polaczenie WhatsApp. W przeciwienstwie do rozlaczenia, **musisz** zeskanowac nowy kod QR, aby ponownie uzyc tej instancji.
</Warning>

***

## Usuwanie instancji

Trwale usun instancje i wszystkie powiazane z nia dane.

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

<Warning>
  Ta operacja jest nieodwracalna. Wszystkie wiadomosci, webhooki i konfiguracja powiazane z ta instancja zostana trwale usuniete.
</Warning>

***

## Pelny przyklad cyklu zycia

Oto kompletny przyklad tworzenia instancji, laczenia jej i odpytywania o kod 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
```

***

## Obsluga bledow

| Kod statusu | Opis                                                                      |
| ----------- | ------------------------------------------------------------------------- |
| `404`       | Instancja nie zostala znaleziona lub nie nalezy do Twojego konta.         |
| `409`       | Instancja jest juz w zadanym stanie (np. juz polaczona).                  |
| `422`       | Nieprawidlowa tresc zapytania (np. brak `name` lub nieprawidlowy `type`). |
| `429`       | Przekroczono limit zapytan. Zobacz [Limity zapytan](/pl/rate-limits).     |