Αναφορά API

Το REST API του WallaWhats σας επιτρέπει να διαχειρίζεστε τηλέφωνα, συνδρομές λογαριασμών X και ιστορικό ειδοποιήσεων μέσω προγραμματισμού — ακριβώς ό,τι θα κάνατε διαφορετικά από το dashboard.

• Base URL: https://api.wallawhats.com
• Content type: application/json
• Έλεγχος ταυτότητας: API key (header)
• Έκδοση: το API είναι σταθερό. Οι αλλαγές που διακόπτουν τη συμβατότητα ανακοινώνονται 30 ημέρες πριν μέσω email σε κάθε λογαριασμό.

Έλεγχος ταυτότητας

Κάθε αίτημα πρέπει να περιλαμβάνει ένα API key στην κεφαλίδα x-api-key:

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

Τα κλειδιά δημιουργούνται στο dashboard στο Settings → API Keys ή μέσω του POST /apikeys. Το πρόθεμα του κλειδιού ξεκινά με bws_ και έχει μήκος 36 χαρακτήρες. Τα κλειδιά εμφανίζονται μία φορά, κατά τη δημιουργία — αν χάσετε κάποιο, διαγράψτε το και δημιουργήστε ένα νέο.

Πεδίο εφαρμογής και λήξη

• Ένα κλειδί πιστοποιεί τον χρήστη που το δημιούργησε. Έχει τα ίδια δικαιώματα με τον χρήστη αυτόν και προσμετράται στα ίδια όρια πλάνου.
• Τα κλειδιά ισχύουν για 365 ημέρες. Εναλλάξτε τα δημιουργώντας ένα νέο κλειδί, μεταβαίνοντας σε αυτό και διαγράφοντας το παλιό.
• Τα κλειδιά που λείπουν, είναι κακοδιαμορφωμένα ή έχουν ανακληθεί επιστρέφουν 401 Unauthorized.

Όρια πλάνου για κλειδιά

Πλάνο	Επιτρεπόμενα κλειδιά
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Η προσπάθεια δημιουργίας περισσότερων από όσα επιτρέπει το πλάνο σας επιστρέφει 400 με "error": "api key limit reached".

Σφάλματα

Τα σφάλματα επιστρέφονται ως JSON με ένα πεδίο error και έναν κωδικό κατάστασης HTTP:

{ "error": "phoneNumber is required" }

Status	Σημασία
400	Μη έγκυρες παράμετροι, υπέρβαση ορίου ή παραβίαση επιχειρηματικού κανόνα
401	API key που λείπει ή δεν είναι έγκυρο
402	Δεν υπάρχουν αρκετές πιστώσεις για την ολοκλήρωση της λειτουργίας
404	Ο πόρος δεν βρέθηκε
500	Σφάλμα διακομιστή — επιχειρήστε ξανά με εκθετική υποχώρηση

Όρια ρυθμού (rate limits)

• Προεπιλογή: 20 αιτήματα/δευτερόλεπτο ανά API key, με εκρηκτικό ρυθμό έως 40.
• Τα endpoints λίστας επιστρέφουν έως 50 στοιχεία ανά σελίδα· χρησιμοποιήστε τον cursor lastKey για σελιδοποίηση.
• Οι κανόνες WAF ενδέχεται να επιστρέψουν 403 σε καταχρηστικά μοτίβα. Επικοινωνήστε με την υποστήριξη αν περιορίζεστε απρόσμενα.

---

User

Αποκτήστε το προφίλ σας

GET /user/profile

Επιστρέφει το προφίλ του πιστοποιημένου χρήστη.

Απάντηση

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

Παράδειγμα

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

---

Phones

Ένα phone είναι ένας επαληθευμένος αριθμός WhatsApp που μπορεί να λαμβάνει ειδοποιήσεις. Πρέπει να επαληθεύσετε ένα τηλέφωνο πριν εγγράψετε σε αυτό έναν λογαριασμό X.

Καταχώριση τηλεφώνου

POST /phones

Δημιουργεί έναν 6ψήφιο κωδικό και τον στέλνει στον αριθμό μέσω WhatsApp. Το τηλέφωνο δημιουργείται σε κατάσταση pending_verification.

Αίτημα

Πεδίο	Τύπος	Απαιτείται	Σημειώσεις
phoneNumber	string	ναι	E.164 format, π.χ. +34612345678
displayName	string	όχι	Φιλική ετικέτα που εμφανίζεται στο dashboard

Απάντηση

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

Σφάλματα

• 400 "invalid phone number format" — δεν είναι E.164
• 400 "phone number limit reached" — υπερβαίνει το όριο του πλάνου (Free/Pro 1, Pro+ 2, Business 3, Enterprise 10)

Παράδειγμα

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

Επαλήθευση τηλεφώνου

POST /phones/verify

Επιβεβαιώνει ένα τηλέφωνο υποβάλλοντας τον 6ψήφιο κωδικό. Οι κωδικοί λήγουν μετά από 15 λεπτά.

Αίτημα

Πεδίο	Τύπος	Απαιτείται
phoneNumber	string (E.164)	ναι
code	string (6 ψηφία)	ναι

Απάντηση

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

Σφάλματα

• 404 "phone not found"
• 400 "invalid code" — λάθος κωδικός
• 400 "code expired" — άνω των 15 λεπτών
• 400 "phone already verified"

Λίστα τηλεφώνων σας

GET /phones

Απάντηση

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

Διαγραφή τηλεφώνου

DELETE /phones/{phoneNumber}

Αφαιρεί το τηλέφωνο και απενεργοποιεί όλες τις συνδρομές που το στόχευαν. Κωδικοποιήστε το + σε URL ως %2B.

Απάντηση

{ "success": true }

Παράδειγμα

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

---

Subscriptions

Μια subscription συνδέει έναν λογαριασμό X που θέλετε να παρακολουθείτε με ένα από τα επαληθευμένα τηλέφωνά σας. Όταν ο λογαριασμός X δημοσιεύει, το WallaWhats στέλνει μια ειδοποίηση WhatsApp σε αυτό το τηλέφωνο.

Δημιουργία συνδρομής

POST /subscriptions

Αίτημα

Πεδίο	Τύπος	Απαιτείται	Σημειώσεις
xUsername	string	ναι	1–15 χαρακτήρες, αλφαριθμητικοί + κάτω παύλα. Το πρόθεμα @ γίνεται δεκτό και αφαιρείται.
phoneNumber	string (E.164)	ναι	Πρέπει να είναι ένα από τα επαληθευμένα τηλέφωνά σας.

Απάντηση

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

Σφάλματα

• 400 "invalid X username format" — αποτυχία regex
• 400 "phone not found" / "phone not verified"
• 400 "subscription limit reached" — δείτε τον πίνακα πλάνου παρακάτω
• 404 "X account not found" — το username δεν επιλύεται στο X

Όρια πλάνου

Πλάνο	Συνδρομές
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Λίστα συνδρομών σας

GET /subscriptions

Απάντηση

{
  "subscriptions": [ /* ίδια δομή με την απάντηση POST /subscriptions */ ],
  "count": 3
}

Διαγραφή συνδρομής

DELETE /subscriptions/{xUsername}

Αντιστοίχιση χωρίς ευαισθησία σε πεζά/κεφαλαία στο xUsername. Αφαιρέστε το @ πριν την αποστολή.

Απάντηση

{ "success": true }

---

Notifications

Κάθε ειδοποίηση που παραδίδει το WallaWhats καταγράφεται εδώ, μαζί με την κατάσταση παράδοσης WhatsApp.

Λίστα ειδοποιήσεων

GET /notifications

Query parameters

Param	Τύπος	Περιγραφή
from	number (ms epoch)	Φιλτράρισμα σε ειδοποιήσεις που δημιουργήθηκαν κατά ή μετά από αυτόν τον χρόνο
to	number (ms epoch)	Φιλτράρισμα σε ειδοποιήσεις που δημιουργήθηκαν κατά ή πριν από αυτόν τον χρόνο
lastKey	string	Cursor σελιδοποίησης που επιστράφηκε από την προηγούμενη απάντηση

Απάντηση

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

Πιθανές τιμές του status: queued, sent, delivered, read, failed.

Το μέγεθος σελίδας είναι 50. Όταν λείπει το lastKey, έχετε φτάσει στο τέλος.

---

API keys

Διαχειριστείτε τα κλειδιά που χρησιμοποιούν οι εφαρμογές σας για να καλούν αυτό το API.

Δημιουργία API key

POST /apikeys

Αίτημα

Πεδίο	Τύπος	Απαιτείται
name	string	όχι, προεπιλογή "Default"

Απάντηση (201 Created)

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

Τιμή που εμφανίζεται μία μόνο φορά

Το apiKey επιστρέφεται μόνο κατά τη δημιουργία. Αποθηκεύστε το αμέσως στον διαχειριστή secrets σας. Οι επόμενες κλήσεις εκθέτουν μόνο το keyPrefix.

Λίστα API keys

GET /apikeys

Απάντηση

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

Διαγραφή API key

DELETE /apikeys/{keyPrefix}

Χρησιμοποιήστε το 12-χαρακτήρων keyPrefix από την απάντηση λίστας — ποτέ ολόκληρο το κλειδί.

Απάντηση

{ "success": true }

---

Γρήγορη εκκίνηση

# 1. Δημιουργήστε ένα κλειδί στο dashboard και εξάγετέ το
export WALLA_API_KEY="bws_prod_..."

# 2. Καταχωρίστε + επαληθεύστε τον αριθμό 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"}'
# -> το τηλέφωνο λαμβάνει έναν κωδικό WhatsApp. Υποβάλετέ τον:
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. Εγγραφείτε σε έναν λογαριασμό 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. Δείτε τις ειδοποιήσεις να καταφθάνουν
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Αυτό ήταν — μόλις ο λογαριασμός X δημοσιεύσει, η ειδοποίηση φτάνει στο τηλέφωνο μέσα σε ~10 δευτερόλεπτα.

Υποστήριξη

Ερωτήσεις API, αναφορές σφαλμάτων ή αιτήματα αύξησης ορίου: ανοίξτε ένα δελτίο από την καρτέλα Support στο dashboard σας ή στείλτε email στο hello@support.wallawhats.com.