Referință API

API-ul REST WallaWhats îți permite să gestionezi telefoane, abonamente la conturi X și istoric de notificări programatic — exact ceea ce ai face altfel din panoul de control.

URL de bază: https://api.wallawhats.com
Tip conținut: application/json
Autentificare: cheie API (antet)
Versionare: API-ul este stabil. Modificările majore sunt anunțate cu 30 de zile în avans prin e-mail către fiecare cont.

Autentificare

Fiecare cerere trebuie să includă o cheie API în antetul x-api-key:

bash

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

Cheile sunt create din panoul de control la Settings → API Keys sau prin POST /apikeys. Un prefix de cheie începe cu bws_ și are 36 de caractere. Cheile sunt afișate o singură dată, la creare — dacă pierzi una, șterge-o și creează una nouă.

Domeniu și expirare

O cheie se autentifică ca utilizatorul care a creat-o. Are aceleași permisiuni ca acel utilizator și se scade din aceleași cote ale planului.
Cheile sunt valabile 365 de zile. Rotește creând o cheie nouă, trecând la ea și ștergând-o pe cea veche.
Cheile lipsă, malformate sau revocate returnează 401 Unauthorized.

Limite ale planurilor pentru chei

Plan	Chei permise
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Încercarea de a crea mai multe chei decât permite planul returnează 400 cu "error": "api key limit reached".

Erori

Erorile sunt returnate ca JSON cu un câmp error și un cod de stare HTTP:

json

{ "error": "phoneNumber is required" }

Stare	Semnificație
`400`	Parametri nevalizi, cotă depășită sau încălcarea unei reguli de afacere
`401`	Cheie API lipsă sau nevalidă
`402`	Credite insuficiente pentru finalizarea operațiunii
`404`	Resursă negăsită
`500`	Eroare de server — te rugăm să reîncerci cu backoff exponențial

Limite de rată

Implicit: 20 de cereri/secundă per cheie API, cu burst până la 40.
Endpoint-urile de listare returnează până la 50 de elemente per pagină; folosește cursorul lastKey pentru paginare.
Regulile WAF pot returna 403 pentru tipare abuzive. Contactează suportul dacă ești limitat neașteptat.

User

Obține-ți profilul

GET /user/profile

Returnează profilul utilizatorului autentificat.

Răspuns

json

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

Exemplu

bash

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

Phones

Un telefon este un număr WhatsApp verificat care poate primi alerte. Trebuie să verifici un telefon înainte de a abona un cont X la el.

Înregistrează un telefon

POST /phones

Generează un cod de 6 cifre și îl trimite la număr prin WhatsApp. Telefonul este creat în starea pending_verification.

Cerere

Câmp	Tip	Obligatoriu	Note
`phoneNumber`	string	da	Format E.164, de ex. `+34612345678`
`displayName`	string	nu	Etichetă prietenoasă afișată în panoul de control

Răspuns

json

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

Erori

400 "invalid phone number format" — nu este E.164
400 "phone number limit reached" — depășește limita planului (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Exemplu

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"}'

Verifică un telefon

POST /phones/verify

Confirmă un telefon prin trimiterea codului de 6 cifre. Codurile expiră după 15 minute.

Cerere

Câmp	Tip	Obligatoriu
`phoneNumber`	string (E.164)	da
`code`	string (6 cifre)	da

Răspuns

json

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

Erori

404 "phone not found"
400 "invalid code" — cod greșit
400 "code expired" — mai vechi de 15 minute
400 "phone already verified"

Listează telefoanele tale

GET /phones

Răspuns

json

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

Șterge un telefon

DELETE /phones/{phoneNumber}

Elimină telefonul și dezactivează toate abonamentele care îl vizau. Codifică URL + ca %2B.

Răspuns

json

{ "success": true }

Exemplu

bash

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

Subscriptions

Un abonament leagă un cont X pe care vrei să îl monitorizezi la unul dintre telefoanele tale verificate. Când contul X postează, WallaWhats trimite o alertă WhatsApp pe acel telefon.

Creează un abonament

POST /subscriptions

Cerere

Câmp	Tip	Obligatoriu	Note
`xUsername`	string	da	1–15 caractere, alfanumerice + subliniere. Prefixul `@` este acceptat și eliminat.
`phoneNumber`	string (E.164)	da	Trebuie să fie unul dintre telefoanele tale verificate.

Răspuns

json

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

Erori

400 "invalid X username format" — eșec regex
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — vezi tabelul planurilor de mai jos
404 "X account not found" — numele de utilizator nu se rezolvă pe X

Limite ale planurilor

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

Listează abonamentele tale

GET /subscriptions

Răspuns

json

{
  "subscriptions": [ /* aceeași formă ca răspunsul POST /subscriptions */ ],
  "count": 3
}

Șterge un abonament

DELETE /subscriptions/{xUsername}

Potrivire insensibilă la majuscule pe xUsername. Elimină @ înainte de trimitere.

Răspuns

json

{ "success": true }

Notifications

Fiecare alertă livrată de WallaWhats este înregistrată aici, împreună cu starea de livrare WhatsApp.

Listează notificările

GET /notifications

Parametri de interogare

Parametru	Tip	Descriere
`from`	number (ms epoch)	Filtrează notificările create la această oră sau după
`to`	number (ms epoch)	Filtrează notificările create la această oră sau înainte
`lastKey`	string	Cursor de paginare returnat de răspunsul anterior

Răspuns

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

Valori posibile pentru status: queued, sent, delivered, read, failed.

Dimensiunea paginii este 50. Când lastKey lipsește, ai ajuns la sfârșit.

API keys

Gestionează cheile pe care aplicațiile tale le folosesc pentru a apela acest API.

Creează o cheie API

POST /apikeys

Cerere

Câmp	Tip	Obligatoriu
`name`	string	nu, implicit `"Default"`

Răspuns (201 Created)

json

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

Valoare afișată o singură dată

apiKey este returnată numai la creare. Stochează-o imediat în managerul tău de secrete. Apelurile ulterioare expun doar keyPrefix.

Listează cheile API

GET /apikeys

Răspuns

json

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

Șterge o cheie API

DELETE /apikeys/{keyPrefix}

Folosește keyPrefix de 12 caractere din răspunsul de listare — niciodată cheia completă.

Răspuns

json

{ "success": true }

Pornire rapidă

bash

# 1. Creează o cheie în panoul de control și exportă-o
export WALLA_API_KEY="bws_prod_..."

# 2. Înregistrează + verifică numărul 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"}'
# -> telefonul primește un cod prin WhatsApp. Trimite-l:
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. Abonează-te la un cont 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. Urmărește cum sosesc alertele
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Asta e tot — odată ce contul X postează, alerta ajunge pe telefon în ~10 secunde.

Suport

Întrebări despre API, rapoarte de erori sau solicitări de creștere a cotei: deschide un tichet din tab-ul Support din panoul tău de control, sau scrie pe e-mail la hello@support.wallawhats.com.

Referință API ​

Autentificare ​

Domeniu și expirare ​

Limite ale planurilor pentru chei ​

Erori ​

Limite de rată ​

User ​

Obține-ți profilul ​

Phones ​

Înregistrează un telefon ​

Verifică un telefon ​

Listează telefoanele tale ​

Șterge un telefon ​

Subscriptions ​

Creează un abonament ​

Listează abonamentele tale ​

Șterge un abonament ​

Notifications ​

Listează notificările ​

API keys ​

Creează o cheie API ​

Listează cheile API ​

Șterge o cheie API ​

Pornire rapidă ​

Suport ​

Referință API

Autentificare

Domeniu și expirare

Limite ale planurilor pentru chei

Erori

Limite de rată

User

Obține-ți profilul

Phones

Înregistrează un telefon

Verifică un telefon

Listează telefoanele tale

Șterge un telefon

Subscriptions

Creează un abonament

Listează abonamentele tale

Șterge un abonament

Notifications

Listează notificările

API keys

Creează o cheie API

Listează cheile API

Șterge o cheie API

Pornire rapidă

Suport