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

Tworzenie instancji

Utworz nowa instancje WhatsApp przypisana do Twojego konta.

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

Odpowiedz:

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

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

Odpowiedz:

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

Pobieranie kodu QR

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

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

Odpowiedz:

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

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

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.

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

Odpowiedz:

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

Zamiast odpytywac, skonfiguruj webhook dla zdarzen instance.connected i instance.qr, aby otrzymywac powiadomienia w czasie rzeczywistym.

Lista wszystkich instancji

Pobierz wszystkie instancje dla Twojego konta.

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

Odpowiedz:

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

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.

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

Restartowanie zachowuje polaczona sesje WhatsApp. Nie bedzie konieczne ponowne skanowanie kodu QR.

Wylogowanie instancji

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

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

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

Usuwanie instancji

Trwale usun instancje i wszystkie powiazane z nia dane.

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

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

Pelny przyklad cyklu zycia

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

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.

Pierwsze Kroki

Przewodniki

Zarzadzanie instancjami

Zarzadzanie instancjami

Typy instancji

Statusy instancji

Przeglad cyklu zycia

Tworzenie instancji

Laczenie instancji

Pobieranie kodu QR

Sprawdzanie statusu instancji

Lista wszystkich instancji

Rozlaczanie instancji

Restartowanie instancji

Wylogowanie instancji

Usuwanie instancji

Pelny przyklad cyklu zycia

Obsluga bledow

​Zarzadzanie instancjami

​Typy instancji

​Statusy instancji

​Przeglad cyklu zycia

​Tworzenie instancji

​Laczenie instancji

​Pobieranie kodu QR

​Sprawdzanie statusu instancji

​Lista wszystkich instancji

​Rozlaczanie instancji

​Restartowanie instancji

​Wylogowanie instancji

​Usuwanie instancji

​Pelny przyklad cyklu zycia

​Obsluga bledow

Zarzadzanie instancjami

Typy instancji

Statusy instancji

Przeglad cyklu zycia

Tworzenie instancji

Laczenie instancji

Pobieranie kodu QR

Sprawdzanie statusu instancji

Lista wszystkich instancji

Rozlaczanie instancji

Restartowanie instancji

Wylogowanie instancji

Usuwanie instancji

Pelny przyklad cyklu zycia

Obsluga bledow