API-Referenz

Mit der WallaWhats-REST-API verwalten Sie Telefonnummern, Abonnements von X-Konten und den Benachrichtigungsverlauf programmatisch — genau das, was Sie sonst im Dashboard tun würden.

Basis-URL: https://api.wallawhats.com
Content-Type: application/json
Authentifizierung: API-Key (Header)
Versionierung: Die API ist stabil. Breaking Changes werden 30 Tage im Voraus per E-Mail an jedes Konto angekündigt.

Authentifizierung

Jede Anfrage muss einen API-Key im Header x-api-key enthalten:

bash

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

Keys werden im Dashboard unter Settings → API Keys oder per POST /apikeys erzeugt. Ein Key-Präfix beginnt mit bws_ und ist 36 Zeichen lang. Keys werden nur einmal, bei der Erzeugung angezeigt — wenn Sie einen verlieren, löschen Sie ihn und erstellen einen neuen.

Geltungsbereich und Ablauf

Ein Key authentifiziert sich als der Nutzer, der ihn erstellt hat. Er hat dieselben Berechtigungen wie dieser Nutzer und zählt auf dieselben Plan-Kontingente.
Keys sind 365 Tage gültig. Rotieren Sie, indem Sie einen neuen Key erstellen, umstellen und den alten löschen.
Fehlende, fehlerhafte oder widerrufene Keys liefern 401 Unauthorized.

Key-Limits je Plan

Plan	Zulässige Keys
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Der Versuch, mehr Keys zu erstellen, als Ihr Plan erlaubt, liefert 400 mit "error": "api key limit reached".

Fehler

Fehler werden als JSON mit einem Feld error und einem HTTP-Statuscode zurückgegeben:

json

{ "error": "phoneNumber is required" }

Status	Bedeutung
`400`	Ungültige Parameter, Kontingent überschritten oder Geschäftsregelverletzung
`401`	Fehlender oder ungültiger API-Key
`402`	Nicht genügend Credits, um den Vorgang abzuschließen
`404`	Ressource nicht gefunden
`500`	Serverfehler — bitte mit exponentiellem Backoff wiederholen

Rate Limits

Standard: 20 Anfragen/Sekunde je API-Key, Burst bis 40.
Listen-Endpunkte liefern bis zu 50 Einträge pro Seite; paginieren Sie mit dem Cursor lastKey.
WAF-Regeln können bei missbräuchlichen Mustern 403 liefern. Melden Sie sich beim Support, falls Sie unerwartet gedrosselt werden.

Benutzer

Eigenes Profil abrufen

GET /user/profile

Gibt das Profil des authentifizierten Nutzers zurück.

Antwort

json

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

Beispiel

bash

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

Telefonnummern

Eine Telefonnummer ist eine verifizierte WhatsApp-Nummer, die Benachrichtigungen empfangen kann. Sie müssen eine Nummer verifizieren, bevor Sie ihr ein X-Konto zuweisen können.

Nummer registrieren

POST /phones

Erzeugt einen 6-stelligen Code und sendet ihn per WhatsApp an die Nummer. Die Nummer wird im Zustand pending_verification angelegt.

Anfrage

Feld	Typ	Pflicht	Hinweise
`phoneNumber`	string	ja	E.164-Format, z. B. `+34612345678`
`displayName`	string	nein	Sprechender Name, angezeigt im Dashboard

Antwort

json

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

Fehler

400 "invalid phone number format" — kein E.164
400 "phone number limit reached" — überschreitet das Plan-Kontingent (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Beispiel

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

Nummer verifizieren

POST /phones/verify

Bestätigt eine Nummer durch Eingabe des 6-stelligen Codes. Codes verfallen nach 15 Minuten.

Anfrage

Feld	Typ	Pflicht
`phoneNumber`	string (E.164)	ja
`code`	string (6 Ziffern)	ja

Antwort

json

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

Fehler

404 "phone not found"
400 "invalid code" — falscher Code
400 "code expired" — älter als 15 Minuten
400 "phone already verified"

Ihre Nummern auflisten

GET /phones

Antwort

json

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

Nummer löschen

DELETE /phones/{phoneNumber}

Entfernt die Nummer und deaktiviert alle Abonnements, die darauf zielen. URL-kodieren Sie das + als %2B.

Antwort

json

{ "success": true }

Beispiel

bash

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

Abonnements

Ein Abonnement verknüpft ein X-Konto, das Sie überwachen möchten, mit einer Ihrer verifizierten Telefonnummern. Wenn das X-Konto postet, sendet WallaWhats eine WhatsApp-Benachrichtigung an diese Nummer.

Abonnement erstellen

POST /subscriptions

Anfrage

Feld	Typ	Pflicht	Hinweise
`xUsername`	string	ja	1–15 Zeichen, alphanumerisch + Unterstrich. Ein vorangestelltes `@` wird akzeptiert und entfernt.
`phoneNumber`	string (E.164)	ja	Muss eine Ihrer verifizierten Nummern sein.

Antwort

json

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

Fehler

400 "invalid X username format" — Regex-Fehler
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — siehe Plan-Tabelle unten
404 "X account not found" — Benutzername lässt sich auf X nicht auflösen

Plan-Limits

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

Ihre Abonnements auflisten

GET /subscriptions

Antwort

json

{
  "subscriptions": [ /* gleiche Form wie die Antwort von POST /subscriptions */ ],
  "count": 3
}

Abonnement löschen

DELETE /subscriptions/{xUsername}

Abgleich bei xUsername ohne Berücksichtigung der Groß-/Kleinschreibung. Entfernen Sie das @ vor dem Senden.

Antwort

json

{ "success": true }

Benachrichtigungen

Jede Benachrichtigung, die WallaWhats zustellt, wird hier protokolliert, zusammen mit dem WhatsApp-Zustellstatus.

Benachrichtigungen auflisten

GET /notifications

Query-Parameter

Parameter	Typ	Beschreibung
`from`	number (ms-Epoch)	Filter auf Benachrichtigungen, die ab diesem Zeitpunkt erstellt wurden
`to`	number (ms-Epoch)	Filter auf Benachrichtigungen, die bis zu diesem Zeitpunkt erstellt wurden
`lastKey`	string	Pagination-Cursor aus der vorherigen Antwort

Antwort

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

Mögliche Werte für status: queued, sent, delivered, read, failed.

Die Seitengröße beträgt 50. Fehlt lastKey, haben Sie das Ende erreicht.

API-Keys

Verwalten Sie die Keys, mit denen Ihre Anwendungen diese API aufrufen.

API-Key erstellen

POST /apikeys

Anfrage

Feld	Typ	Pflicht
`name`	string	nein, Standardwert `"Default"`

Antwort (201 Created)

json

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

Nur einmal sichtbarer Wert

apiKey wird nur bei der Erstellung zurückgegeben. Speichern Sie ihn sofort in Ihrem Secrets-Manager. Nachfolgende Aufrufe zeigen nur noch keyPrefix.

Ihre API-Keys auflisten

GET /apikeys

Antwort

json

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

API-Key löschen

DELETE /apikeys/{keyPrefix}

Verwenden Sie den 12-stelligen keyPrefix aus der Listenantwort — niemals den vollständigen Key.

Antwort

json

{ "success": true }

Schnellstart

bash

# 1. Key im Dashboard erstellen und exportieren
export WALLA_API_KEY="bws_prod_..."

# 2. WhatsApp-Nummer registrieren + verifizieren
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"}'
# -> das Telefon erhält einen WhatsApp-Code. Senden Sie ihn ab:
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-Konto abonnieren
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. Benachrichtigungen entgegennehmen
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Das war's — sobald das X-Konto postet, landet die Benachrichtigung innerhalb von etwa 10 Sekunden auf dem Telefon.

Support

API-Fragen, Fehlerberichte oder Anfragen zur Kontingenterhöhung: Öffnen Sie ein Ticket über den Support-Tab in Ihrem Dashboard oder schreiben Sie an hello@support.wallawhats.com.

API-Referenz ​

Authentifizierung ​

Geltungsbereich und Ablauf ​

Key-Limits je Plan ​

Fehler ​

Rate Limits ​

Benutzer ​

Eigenes Profil abrufen ​

Telefonnummern ​

Nummer registrieren ​

Nummer verifizieren ​

Ihre Nummern auflisten ​

Nummer löschen ​

Abonnements ​

Abonnement erstellen ​

Ihre Abonnements auflisten ​

Abonnement löschen ​

Benachrichtigungen ​

Benachrichtigungen auflisten ​

API-Keys ​

API-Key erstellen ​

Ihre API-Keys auflisten ​

API-Key löschen ​

Schnellstart ​

Support ​

API-Referenz

Authentifizierung

Geltungsbereich und Ablauf

Key-Limits je Plan

Fehler

Rate Limits

Benutzer

Eigenes Profil abrufen

Telefonnummern

Nummer registrieren

Nummer verifizieren

Ihre Nummern auflisten

Nummer löschen

Abonnements

Abonnement erstellen

Ihre Abonnements auflisten

Abonnement löschen

Benachrichtigungen

Benachrichtigungen auflisten

API-Keys

API-Key erstellen

Ihre API-Keys auflisten

API-Key löschen

Schnellstart

Support