Przejdź do głównej treści

​
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:
TypOpis
wahaSamodzielnie hostowane WhatsApp Web API poprzez WAHA Plus. Pelna obsluga funkcji, w tym grup, etykiet i kontaktow.
cloud_apiOficjalne WhatsApp Business Cloud API od Meta. Wymaga konta Meta Business.

​
Statusy instancji

W trakcie cyklu zycia instancja przechodzi przez nastepujace statusy:
StatusOpis
createdRekord instancji istnieje, ale nie zostal jeszcze uruchomiony.
startingInstancja uruchamia sie i inicjalizuje sesje WhatsApp.
scan_qrInstancja czeka na zeskanowanie kodu QR telefonem.
connectedSesja WhatsApp jest aktywna i gotowa do wysylania/odbierania wiadomosci.
disconnectedSesja zostala zatrzymana lub utracono polaczenie. Mozna ja ponownie polaczyc.
failedInstancja 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"
  }'
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"
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 statusuOpis
404Instancja nie zostala znaleziona lub nie nalezy do Twojego konta.
409Instancja jest juz w zadanym stanie (np. juz polaczona).
422Nieprawidlowa tresc zapytania (np. brak name lub nieprawidlowy type).
429Przekroczono limit zapytan. Zobacz Limity zapytan.