API viide

WallaWhatsi REST API võimaldab programselt hallata telefone, X-konto tellimusi ja teavituste ajalugu — täpselt nii, nagu teeksid seda töölaualt.

• Põhi-URL: https://api.wallawhats.com
• Content type: application/json
• Autentimine: API-võti (päis)
• Versioonimine: API on stabiilne. Murendavatest muudatustest teavitatakse 30 päeva ette e-posti teel igale kontole.

Autentimine

Iga päring peab sisaldama API-võtit päises x-api-key:

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

Võtmed luuakse töölaual jaotises Settings → API Keys või päringuga POST /apikeys. Võtme prefiks algab tähisega bws_ ja on 36 tähemärgi pikkune. Võtmed kuvatakse vaid ühel korral, loomise hetkel — kui kaotad võtme, kustuta see ja loo uus.

Ulatus ja kehtivus

• Võti autentib kasutaja, kes selle lõi. Sellel on samad õigused mis sellel kasutajal ja see arvestatakse samasse tellimuse kvooti.
• Võtmed kehtivad 365 päeva. Rotatsiooni tegemiseks loo uus võti, vaheta üle ja kustuta vana.
• Puuduv, valeformaadis või tühistatud võti tagastab 401 Unauthorized.

Tellimuse piirangud võtmetele

Tellimus	Lubatud võtmeid
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Katse luua rohkem, kui tellimus lubab, tagastab 400 koos teatega "error": "api key limit reached".

Vead

Vead tagastatakse JSON-vormingus väljaga error ja HTTP-staatuskoodiga:

{ "error": "phoneNumber is required" }

Staatus	Tähendus
400	Vigased parameetrid, kvoot ületatud või ärireegli rikkumine
401	Puuduv või vigane API-võti
402	Krediite ei piisa operatsiooni lõpetamiseks
404	Ressurssi ei leitud
500	Serveri viga — palun proovi uuesti eksponentsiaalse viitega

Päringupiirangud

• Vaikimisi: 20 päringut sekundis API-võtme kohta, puhanguga 40-ni.
• Loendi otspunktid tagastavad kuni 50 kirjet lehe kohta; kasuta lastKey kursorit lehitsemiseks.
• WAF-reeglid võivad kuritarvituslike mustrite korral tagastada 403. Võta ühendust toega, kui sind ootamatult piiratakse.

---

User

Hangi oma profiil

GET /user/profile

Tagastab autenditud kasutaja profiili.

Vastus

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

Näide

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

---

Phones

Telefon on kinnitatud WhatsApp-number, mis saab vastu võtta teavitusi. Pead telefoni kinnitama, enne kui saad sellega X-kontot siduda.

Registreeri telefon

POST /phones

Loob 6-kohalise koodi ja saadab selle numbrile WhatsAppi kaudu. Telefon luuakse olekusse pending_verification.

Päring

Väli	Tüüp	Kohustuslik	Märkused
phoneNumber	string	jah	E.164-vorming, nt +34612345678
displayName	string	ei	Sõbralik silt, mis kuvatakse töölaual

Vastus

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

Vead

• 400 "invalid phone number format" — pole E.164
• 400 "phone number limit reached" — ületab tellimuse limiidi (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Näide

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

Kinnita telefon

POST /phones/verify

Kinnitab telefoni 6-kohalise koodi esitamise teel. Koodid aeguvad 15 minuti pärast.

Päring

Väli	Tüüp	Kohustuslik
phoneNumber	string (E.164)	jah
code	string (6 numbrit)	jah

Vastus

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

Vead

• 404 "phone not found"
• 400 "invalid code" — vale kood
• 400 "code expired" — üle 15 minuti vana
• 400 "phone already verified"

Loetle oma telefonid

GET /phones

Vastus

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

Kustuta telefon

DELETE /phones/{phoneNumber}

Eemaldab telefoni ja deaktiveerib kõik sellele suunatud tellimused. URL-kodeeri + kui %2B.

Vastus

{ "success": true }

Näide

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

---

Subscriptions

Tellimus seob jälgitava X-konto ühega sinu kinnitatud telefonidest. Kui X-konto postitab, saadab WallaWhats WhatsApp-teavituse sellele telefonile.

Loo tellimus

POST /subscriptions

Päring

Väli	Tüüp	Kohustuslik	Märkused
xUsername	string	jah	1–15 tähemärki, tähtnumbrilised + alakriips. @-prefiks on aktsepteeritud ja eemaldatakse.
phoneNumber	string (E.164)	jah	Peab olema üks sinu kinnitatud telefonidest.

Vastus

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

Vead

• 400 "invalid X username format" — regex ei vasta
• 400 "phone not found" / "phone not verified"
• 400 "subscription limit reached" — vaata tellimuste tabelit allpool
• 404 "X account not found" — kasutajanimi ei leidu X-is

Tellimuse piirangud

Tellimus	Tellimusi
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Loetle oma tellimused

GET /subscriptions

Vastus

{
  "subscriptions": [ /* sama kuju mis POST /subscriptions vastus */ ],
  "count": 3
}

Kustuta tellimus

DELETE /subscriptions/{xUsername}

Suurtähtede suhtes tundetu vastavus väljale xUsername. Eemalda @ enne saatmist.

Vastus

{ "success": true }

---

Notifications

Iga WallaWhatsi edastatud teavitus logitakse siia koos WhatsApp-i kohaletoimetamise olekuga.

Loetle teavitused

GET /notifications

Päringu parameetrid

Parameeter	Tüüp	Kirjeldus
from	number (ms epoch)	Filtreeri teavitused, mis loodi sel ajal või pärast seda
to	number (ms epoch)	Filtreeri teavitused, mis loodi sel ajal või enne seda
lastKey	string	Lehitsemise kursor, mille tagastas eelmine vastus

Vastus

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

Võimalikud status väärtused: queued, sent, delivered, read, failed.

Lehe suurus on 50. Kui lastKey puudub, oled jõudnud lõppu.

---

API keys

Halda võtmeid, mida su rakendused selle API kutsumiseks kasutavad.

Loo API-võti

POST /apikeys

Päring

Väli	Tüüp	Kohustuslik
name	string	ei, vaikimisi "Default"

Vastus (201 Created)

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

Kuvatakse ainult kord

apiKey tagastatakse ainult loomise hetkel. Salvesta see kohe oma saladuste haldurisse. Järgmistel kutsetel avaldatakse ainult keyPrefix.

Loetle oma API-võtmed

GET /apikeys

Vastus

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

Kustuta API-võti

DELETE /apikeys/{keyPrefix}

Kasuta loendi vastuse 12-tähemärgilist keyPrefix-i — mitte kunagi kogu võtit.

Vastus

{ "success": true }

---

Kiirstart

# 1. Loo töölaual võti ja ekspordi see
export WALLA_API_KEY="bws_prod_..."

# 2. Registreeri + kinnita oma WhatsApp-number
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 saab WhatsApp-koodi. Esita see:
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. Telli X-konto
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. Vaata, kuidas teavitused saabuvad
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Ongi kõik — kui X-konto postitab, jõuab teavitus telefonile umbes 10 sekundiga.

Tugi

API-küsimused, vigade teated või kvoodi suurendamise taotlused: ava pilet oma töölaual Support-vahekaardil või saada e-kiri aadressile hello@support.wallawhats.com.