Dokumentacja API

REST API WallaWhats pozwala programowo zarządzać telefonami, subskrypcjami kont X oraz historią powiadomień — czyli dokładnie tym, co można zrobić z poziomu panelu.

URL bazowy: https://api.wallawhats.com
Typ zawartości: application/json
Uwierzytelnianie: klucz API (nagłówek)
Wersjonowanie: API jest stabilne. Zmiany niezgodne wstecz są ogłaszane z 30-dniowym wyprzedzeniem e-mailem na każde konto.

Uwierzytelnianie

Każde żądanie musi zawierać klucz API w nagłówku x-api-key:

bash

curl https://api.wallawhats.com/user/profile \
  -H "x-api-key: bws_prod_00000000000000000000000000000000"

Klucze tworzy się w panelu w Ustawienia → Klucze API lub przez POST /apikeys. Prefiks klucza zaczyna się od bws_ i ma 36 znaków. Klucze są pokazywane tylko raz, podczas tworzenia — jeśli zgubisz klucz, usuń go i utwórz nowy.

Zakres i wygasanie

Klucz uwierzytelnia się jako użytkownik, który go utworzył. Ma te same uprawnienia co ten użytkownik i jest liczony do tych samych limitów planu.
Klucze są ważne przez 365 dni. Rotację wykonuje się tworząc nowy klucz, przełączając się na niego i usuwając stary.
Brakujące, zniekształcone lub odwołane klucze zwracają 401 Unauthorized.

Limity planu dla kluczy

Plan	Dozwolone klucze
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Próba utworzenia większej liczby kluczy niż dopuszcza plan zwraca 400 z "error": "api key limit reached".

Błędy

Błędy zwracane są jako JSON z polem error oraz kodem statusu HTTP:

json

{ "error": "phoneNumber is required" }

Status	Znaczenie
`400`	Nieprawidłowe parametry, przekroczony limit lub naruszenie reguły biznesowej
`401`	Brakujący lub nieprawidłowy klucz API
`402`	Za mało środków, aby wykonać operację
`404`	Nie znaleziono zasobu
`500`	Błąd serwera — spróbuj ponownie z wykładniczym opóźnieniem

Limity zapytań

Domyślnie: 20 żądań/sekundę na klucz API, z burst do 40.
Endpointy listujące zwracają do 50 elementów na stronę; do stronicowania użyj kursora lastKey.
Reguły WAF mogą zwrócić 403 przy wzorcach nadużyć. Skontaktuj się z pomocą, jeśli doświadczasz nieoczekiwanego ograniczania.

Użytkownik

Pobranie profilu

GET /user/profile

Zwraca profil uwierzytelnionego użytkownika.

Odpowiedź

json

{
  "userId": "5a4cbd70-...",
  "email": "jane@example.com",
  "name": "Jane",
  "plan": "pro_plus",
  "createdAt": 1745000000000
}

Przykład

bash

curl https://api.wallawhats.com/user/profile \
  -H "x-api-key: bws_prod_..."

Telefony

Telefon to zweryfikowany numer WhatsApp, który może otrzymywać alerty. Numer trzeba zweryfikować przed przypisaniem do niego subskrypcji konta X.

Rejestracja telefonu

POST /phones

Generuje 6-cyfrowy kod i wysyła go na numer przez WhatsApp. Telefon jest tworzony w stanie pending_verification.

Żądanie

Pole	Typ	Wymagane	Uwagi
`phoneNumber`	string	tak	format E.164, np. `+34612345678`
`displayName`	string	nie	Czytelna etykieta wyświetlana w panelu

Odpowiedź

json

{ "phoneNumber": "+34612345678", "status": "pending_verification" }

Błędy

400 "invalid phone number format" — niezgodny z E.164
400 "phone number limit reached" — przekroczony limit planu (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Przykład

bash

curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: bws_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+34612345678", "displayName": "Work"}'

Weryfikacja telefonu

POST /phones/verify

Potwierdza telefon, wysyłając 6-cyfrowy kod. Kody wygasają po 15 minutach.

Żądanie

Pole	Typ	Wymagane
`phoneNumber`	string (E.164)	tak
`code`	string (6 cyfr)	tak

Odpowiedź

json

{ "phoneNumber": "+34612345678", "status": "verified" }

Błędy

404 "phone not found"
400 "invalid code" — nieprawidłowy kod
400 "code expired" — starszy niż 15 minut
400 "phone already verified"

Lista telefonów

GET /phones

Odpowiedź

json

{
  "phones": [
    {
      "phoneNumber": "+34612345678",
      "status": "verified",
      "displayName": "Work",
      "createdAt": 1745000000000,
      "verifiedAt": 1745000060000
    }
  ],
  "count": 1
}

Usunięcie telefonu

DELETE /phones/{phoneNumber}

Usuwa telefon i dezaktywuje wszystkie subskrypcje, które go używały. Zakoduj + w URL jako %2B.

Odpowiedź

json

{ "success": true }

Przykład

bash

curl -X DELETE "https://api.wallawhats.com/phones/%2B34612345678" \
  -H "x-api-key: bws_prod_..."

Subskrypcje

Subskrypcja wiąże konto X, które chcesz monitorować, z jednym z Twoich zweryfikowanych telefonów. Gdy konto X publikuje, WallaWhats wysyła alert WhatsApp na ten telefon.

Utworzenie subskrypcji

POST /subscriptions

Żądanie

Pole	Typ	Wymagane	Uwagi
`xUsername`	string	tak	1–15 znaków, alfanumeryczne + podkreślenie. Prefiks `@` jest akceptowany i usuwany.
`phoneNumber`	string (E.164)	tak	Musi być jednym z Twoich zweryfikowanych telefonów.

Odpowiedź

json

{
  "xUsername": "elonmusk",
  "xUserId": "44196397",
  "xDisplayName": "Elon Musk",
  "xProfileImage": "https://pbs.twimg.com/...",
  "phoneNumber": "+34612345678",
  "isActive": true,
  "createdAt": 1745000000000
}

Błędy

400 "invalid X username format" — niezgodny z wyrażeniem regularnym
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — zobacz tabelę planów poniżej
404 "X account not found" — nazwa użytkownika nie rozwiązuje się w X

Limity planów

Plan	Subskrypcje
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Lista subskrypcji

GET /subscriptions

Odpowiedź

json

{
  "subscriptions": [ /* ten sam kształt co odpowiedź POST /subscriptions */ ],
  "count": 3
}

Usunięcie subskrypcji

DELETE /subscriptions/{xUsername}

Dopasowanie xUsername bez rozróżniania wielkości liter. Przed wysłaniem usuń @.

Odpowiedź

json

{ "success": true }

Powiadomienia

Każdy alert wysłany przez WallaWhats jest tutaj rejestrowany wraz ze statusem dostarczenia w WhatsApp.

Lista powiadomień

GET /notifications

Parametry zapytania

Parametr	Typ	Opis
`from`	number (ms epoch)	Filtruj powiadomienia utworzone w tym czasie lub później
`to`	number (ms epoch)	Filtruj powiadomienia utworzone w tym czasie lub wcześniej
`lastKey`	string	Kursor stronicowania zwrócony w poprzedniej odpowiedzi

Odpowiedź

json

{
  "notifications": [
    {
      "notificationId": "a1b2c3d4-...",
      "userId": "5a4cbd70-...",
      "phoneNumber": "+34612345678",
      "xUsername": "elonmusk",
      "tweetId": "1797123456789000000",
      "tweetText": "...",
      "tweetUrl": "https://x.com/elonmusk/status/...",
      "waMessageId": "wamid.HBgN...",
      "status": "delivered",
      "errorMessage": null,
      "createdAt": 1745000000000,
      "updatedAt": 1745000002000
    }
  ],
  "lastKey": "eyJOT1RJRklDQVRJT05fSUQi..."
}

Możliwe wartości status: queued, sent, delivered, read, failed.

Rozmiar strony to 50. Gdy lastKey nie występuje, dotarłeś do końca.

Klucze API

Zarządzaj kluczami, których Twoje aplikacje używają do wywoływania tego API.

Tworzenie klucza API

POST /apikeys

Żądanie

Pole	Typ	Wymagane
`name`	string	nie, domyślnie `"Default"`

Odpowiedź (201 Created)

json

{
  "apiKey": "bws_prod_00000000000000000000000000000000",
  "keyPrefix": "bws_prod_00",
  "keyName": "CI server",
  "createdAt": 1745000000000,
  "expiresAt": 1776536000000
}

Wartość widoczna raz

apiKey jest zwracany tylko podczas tworzenia. Natychmiast zapisz go w menedżerze sekretów. Kolejne wywołania ujawniają tylko keyPrefix.

Lista kluczy API

GET /apikeys

Odpowiedź

json

[
  {
    "keyPrefix": "bws_prod_00",
    "keyName": "CI server",
    "createdAt": 1745000000000,
    "lastUsedAt": 1745086400000,
    "expiresAt": 1776536000000
  }
]

Usunięcie klucza API

DELETE /apikeys/{keyPrefix}

Użyj 12-znakowego keyPrefix z odpowiedzi listującej — nigdy pełnego klucza.

Odpowiedź

json

{ "success": true }

Szybki start

bash

# 1. Utwórz klucz w panelu i wyeksportuj go
export WALLA_API_KEY="bws_prod_..."

# 2. Zarejestruj i zweryfikuj numer WhatsApp
curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+34612345678","displayName":"Mobile"}'
# -> telefon otrzymuje kod WhatsApp. Wyślij go:
curl -X POST https://api.wallawhats.com/phones/verify \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+34612345678","code":"123456"}'

# 3. Subskrybuj konto X
curl -X POST https://api.wallawhats.com/subscriptions \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xUsername":"elonmusk","phoneNumber":"+34612345678"}'

# 4. Obserwuj napływające alerty
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

To wszystko — gdy konto X opublikuje post, alert trafi na telefon w około 10 sekund.

Wsparcie

Pytania o API, zgłoszenia błędów lub prośby o zwiększenie limitów: otwórz zgłoszenie z zakładki Wsparcie w panelu lub napisz na hello@support.wallawhats.com.

Dokumentacja API ​

Uwierzytelnianie ​

Zakres i wygasanie ​

Limity planu dla kluczy ​

Błędy ​

Limity zapytań ​

Użytkownik ​

Pobranie profilu ​

Telefony ​

Rejestracja telefonu ​

Weryfikacja telefonu ​

Lista telefonów ​

Usunięcie telefonu ​

Subskrypcje ​

Utworzenie subskrypcji ​

Lista subskrypcji ​

Usunięcie subskrypcji ​

Powiadomienia ​

Lista powiadomień ​

Klucze API ​

Tworzenie klucza API ​

Lista kluczy API ​

Usunięcie klucza API ​

Szybki start ​

Wsparcie ​

Dokumentacja API

Uwierzytelnianie

Zakres i wygasanie

Limity planu dla kluczy

Błędy

Limity zapytań

Użytkownik

Pobranie profilu

Telefony

Rejestracja telefonu

Weryfikacja telefonu

Lista telefonów

Usunięcie telefonu

Subskrypcje

Utworzenie subskrypcji

Lista subskrypcji

Usunięcie subskrypcji

Powiadomienia

Lista powiadomień

Klucze API

Tworzenie klucza API

Lista kluczy API

Usunięcie klucza API

Szybki start

Wsparcie