API-viite

WallaWhats REST API antaa sinun hallita puhelimia, X-tilien tilauksia ja ilmoitushistoriaa ohjelmallisesti — täsmälleen niin kuin tekisit kojelaudalla.

• Perus-URL: https://api.wallawhats.com
• Content type: application/json
• Todennus: API-avain (otsake)
• Versiointi: API on vakaa. Rikkovat muutokset ilmoitetaan 30 päivää etukäteen sähköpostitse jokaiselle tilille.

Todennus

Jokaisen pyynnön täytyy sisältää API-avain x-api-key-otsakkeessa:

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

Avaimet luodaan kojelaudalla kohdassa Settings → API Keys tai kutsulla POST /apikeys. Avaimen etuliite alkaa bws_ ja on 36 merkkiä pitkä. Avaimet näytetään vain kerran, luontihetkellä — jos häviät avaimen, poista se ja luo uusi.

Laajuus ja voimassaolo

• Avain todentaa käyttäjän, joka sen loi. Sillä on samat oikeudet kuin kyseisellä käyttäjällä ja se lasketaan samoihin tilauskiintiöihin.
• Avaimet ovat voimassa 365 päivää. Kierrätä luomalla uusi avain, vaihtamalla, ja poistamalla vanha.
• Puuttuva, virheellinen tai peruutettu avain palauttaa 401 Unauthorized.

Tilauksen rajat avaimille

Tilaus	Sallittuja avaimia
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Yritys luoda enemmän kuin tilauksesi sallii palauttaa 400 viestillä "error": "api key limit reached".

Virheet

Virheet palautetaan JSON-muodossa error-kentän ja HTTP-tilakoodin kera:

{ "error": "phoneNumber is required" }

Tila	Merkitys
400	Virheelliset parametrit, kiintiö ylitetty tai liiketoimintasäännön rikkomus
401	Puuttuva tai virheellinen API-avain
402	Krediittejä ei ole tarpeeksi operaation suorittamiseen
404	Resurssia ei löytynyt
500	Palvelinvirhe — yritä uudelleen eksponentiaalisella viiveellä

Pyyntörajat

• Oletus: 20 pyyntöä/sekunti per API-avain, purske 40:een.
• Listausendpointit palauttavat enintään 50 kohdetta sivua kohden; käytä lastKey-kursoria sivutukseen.
• WAF-säännöt voivat palauttaa 403:n vilpillisiin kuvioihin. Ota yhteyttä tukeen, jos törmäät rajoituksiin odottamatta.

---

User

Hae profiilisi

GET /user/profile

Palauttaa todennetun käyttäjän profiilin.

Vastaus

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

Esimerkki

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

---

Phones

Puhelin on vahvistettu WhatsApp-numero, joka voi vastaanottaa hälytyksiä. Sinun täytyy vahvistaa puhelin ennen X-tilin tilaamista siihen.

Rekisteröi puhelin

POST /phones

Luo 6-numeroisen koodin ja lähettää sen numeroon WhatsAppin kautta. Puhelin luodaan pending_verification-tilaan.

Pyyntö

Kenttä	Tyyppi	Pakollinen	Huomiot
phoneNumber	string	kyllä	E.164-muoto, esim. +34612345678
displayName	string	ei	Ystävällinen etiketti, joka näkyy kojelaudalla

Vastaus

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

Virheet

• 400 "invalid phone number format" — ei E.164
• 400 "phone number limit reached" — ylittää tilauksen sallimat (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Esimerkki

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

Vahvista puhelin

POST /phones/verify

Vahvistaa puhelimen lähettämällä 6-numeroisen koodin. Koodit vanhenevat 15 minuutin jälkeen.

Pyyntö

Kenttä	Tyyppi	Pakollinen
phoneNumber	string (E.164)	kyllä
code	string (6 numeroa)	kyllä

Vastaus

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

Virheet

• 404 "phone not found"
• 400 "invalid code" — väärä koodi
• 400 "code expired" — yli 15 minuuttia vanha
• 400 "phone already verified"

Listaa puhelimesi

GET /phones

Vastaus

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

Poista puhelin

DELETE /phones/{phoneNumber}

Poistaa puhelimen ja deaktivoi kaikki kyseiseen numeroon kohdistuneet tilaukset. URL-koodaa + muotoon %2B.

Vastaus

{ "success": true }

Esimerkki

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

---

Subscriptions

Tilaus yhdistää seurattavan X-tilin johonkin vahvistamistasi puhelimista. Kun X-tili julkaisee viestin, WallaWhats lähettää WhatsApp-hälytyksen kyseiseen puhelimeen.

Luo tilaus

POST /subscriptions

Pyyntö

Kenttä	Tyyppi	Pakollinen	Huomiot
xUsername	string	kyllä	1–15 merkkiä, aakkosnumeerinen + alaviiva. @-etuliite hyväksytään ja poistetaan.
phoneNumber	string (E.164)	kyllä	Täytyy olla yksi vahvistetuista puhelimistasi.

Vastaus

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

Virheet

• 400 "invalid X username format" — regex-virhe
• 400 "phone not found" / "phone not verified"
• 400 "subscription limit reached" — katso tilaustaulukko alla
• 404 "X account not found" — käyttäjänimi ei vastaa mitään X:ssä

Tilauksen rajat

Tilaus	Tilauksia
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Listaa tilauksesi

GET /subscriptions

Vastaus

{
  "subscriptions": [ /* sama muoto kuin POST /subscriptions -vastauksessa */ ],
  "count": 3
}

Poista tilaus

DELETE /subscriptions/{xUsername}

Kirjainkoosta riippumaton täsmäys kentässä xUsername. Poista @ ennen lähetystä.

Vastaus

{ "success": true }

---

Notifications

Jokainen WallaWhatsin toimittama hälytys kirjataan tänne yhdessä WhatsApp-toimitustilansa kanssa.

Listaa ilmoitukset

GET /notifications

Kyselyparametrit

Parametri	Tyyppi	Kuvaus
from	number (ms epoch)	Suodata ilmoitukset, jotka on luotu tämän ajan jälkeen tai sen aikaan
to	number (ms epoch)	Suodata ilmoitukset, jotka on luotu tänä aikana tai sitä ennen
lastKey	string	Sivutuskursori, joka palautettiin edellisessä vastauksessa

Vastaus

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

Mahdolliset status-arvot: queued, sent, delivered, read, failed.

Sivun koko on 50. Kun lastKey puuttuu, olet saavuttanut lopun.

---

API keys

Hallitse avaimia, joita sovelluksesi käyttävät tämän API:n kutsumiseen.

Luo API-avain

POST /apikeys

Pyyntö

Kenttä	Tyyppi	Pakollinen
name	string	ei, oletus "Default"

Vastaus (201 Created)

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

Näytetään vain kerran

apiKey palautetaan vain luontihetkellä. Tallenna se salaisuushallintajärjestelmääsi välittömästi. Myöhemmät kutsut paljastavat vain keyPrefix-kentän.

Listaa API-avaimesi

GET /apikeys

Vastaus

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

Poista API-avain

DELETE /apikeys/{keyPrefix}

Käytä listausvastauksen 12-merkkistä keyPrefix-arvoa — älä koskaan koko avainta.

Vastaus

{ "success": true }

---

Pikaopas

# 1. Luo avain kojelaudalla ja vie se
export WALLA_API_KEY="bws_prod_..."

# 2. Rekisteröi + vahvista WhatsApp-numerosi
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"}'
# -> puhelin saa WhatsApp-koodin. Lähetä se:
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. Tilaa X-tili
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. Katso, kuinka hälytykset virtaavat
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Siinä se — kun X-tili julkaisee, hälytys saapuu puhelimeen noin 10 sekunnissa.

Tuki

API-kysymykset, virheraportit tai kiintiökorotuspyynnöt: avaa tiketti kojelautasi Support-välilehdeltä tai lähetä sähköpostia osoitteeseen hello@support.wallawhats.com.