API Reference

The WallaWhats REST API lets you manage phones, X account subscriptions, and notification history programmatically — exactly what you'd otherwise do from the dashboard.

Base URL: https://api.wallawhats.com
Content type: application/json
Authentication: API key (header)
Versioning: the API is stable. Breaking changes are announced 30 days in advance via email to every account.

Authentication

Every request must include an API key in the x-api-key header:

bash

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

Keys are created in the dashboard under Settings → API Keys or via POST /apikeys. A key prefix starts with bws_ and is 36 characters long. Keys are shown once, at creation — if you lose one, delete it and create a new one.

Scope and expiry

A key authenticates as the user that created it. It has the same permissions as that user and counts against the same plan quotas.
Keys are valid for 365 days. Rotate by creating a new key, switching over, and deleting the old one.
Missing, malformed, or revoked keys return 401 Unauthorized.

Plan limits on keys

Plan	Keys allowed
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Attempting to create more than your plan allows returns 400 with "error": "api key limit reached".

Errors

Errors are returned as JSON with an error field and an HTTP status code:

json

{ "error": "phoneNumber is required" }

Status	Meaning
`400`	Invalid parameters, quota exceeded, or business-rule violation
`401`	Missing or invalid API key
`402`	Not enough credits to complete the operation
`404`	Resource not found
`500`	Server error — please retry with exponential backoff

Rate limits

Default: 20 requests/second per API key, bursting to 40.
List endpoints return up to 50 items per page; use the lastKey cursor to paginate.
WAF rules may return 403 on abusive patterns. Contact support if you're being rate-limited unexpectedly.

User

Get your profile

GET /user/profile

Returns the authenticated user's profile.

Response

json

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

Example

bash

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

Phones

A phone is a verified WhatsApp number that can receive alerts. You must verify a phone before subscribing an X account to it.

Register a phone

POST /phones

Generates a 6-digit code and sends it to the number via WhatsApp. The phone is created in pending_verification state.

Request

Field	Type	Required	Notes
`phoneNumber`	string	yes	E.164 format, e.g. `+34612345678`
`displayName`	string	no	Friendly label shown in the dashboard

Response

json

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

Errors

400 "invalid phone number format" — not E.164
400 "phone number limit reached" — exceeds plan allowance (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Example

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

Verify a phone

POST /phones/verify

Confirms a phone by submitting the 6-digit code. Codes expire after 15 minutes.

Request

Field	Type	Required
`phoneNumber`	string (E.164)	yes
`code`	string (6 digits)	yes

Response

json

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

Errors

404 "phone not found"
400 "invalid code" — wrong code
400 "code expired" — over 15 minutes old
400 "phone already verified"

List your phones

GET /phones

Response

json

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

Delete a phone

DELETE /phones/{phoneNumber}

Removes the phone and deactivates any subscriptions that targeted it. URL-encode the + as %2B.

Response

json

{ "success": true }

Example

bash

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

Subscriptions

A subscription ties an X account you want to monitor to one of your verified phones. When the X account posts, WallaWhats sends a WhatsApp alert to that phone.

Create a subscription

POST /subscriptions

Request

Field	Type	Required	Notes
`xUsername`	string	yes	1–15 chars, alphanumeric + underscore. `@` prefix is accepted and stripped.
`phoneNumber`	string (E.164)	yes	Must be one of your verified phones.

Response

json

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

Errors

400 "invalid X username format" — regex fail
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — see plan table below
404 "X account not found" — username doesn't resolve on X

Plan limits

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

List your subscriptions

GET /subscriptions

Response

json

{
  "subscriptions": [ /* same shape as POST /subscriptions response */ ],
  "count": 3
}

Delete a subscription

DELETE /subscriptions/{xUsername}

Case-insensitive match on xUsername. Strip the @ before sending.

Response

json

{ "success": true }

Notifications

Every alert WallaWhats delivers is logged here, along with its WhatsApp delivery status.

List notifications

GET /notifications

Query parameters

Param	Type	Description
`from`	number (ms epoch)	Filter to notifications created at or after this time
`to`	number (ms epoch)	Filter to notifications created at or before this time
`lastKey`	string	Pagination cursor returned by the previous response

Response

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

Possible status values: queued, sent, delivered, read, failed.

Page size is 50. When lastKey is absent, you've reached the end.

API keys

Manage the keys your applications use to call this API.

Create an API key

POST /apikeys

Request

Field	Type	Required
`name`	string	no, defaults to `"Default"`

Response (201 Created)

json

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

Show-once value

apiKey is returned only at creation. Store it in your secrets manager immediately. Subsequent calls only expose the keyPrefix.

List your API keys

GET /apikeys

Response

json

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

Delete an API key

DELETE /apikeys/{keyPrefix}

Use the 12-character keyPrefix from the list response — never the full key.

Response

json

{ "success": true }

Quickstart

bash

# 1. Create a key in the dashboard and export it
export WALLA_API_KEY="bws_prod_..."

# 2. Register + verify your 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"}'
# -> the phone receives a WhatsApp code. Submit it:
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. Subscribe to an X account
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. Watch alerts roll in
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

That's it — once the X account posts, the alert lands on the phone within ~10 seconds.

Support

API questions, bug reports, or quota-increase requests: open a ticket from the Support tab in your dashboard, or email hello@support.wallawhats.com.

API Reference ​

Authentication ​

Scope and expiry ​

Plan limits on keys ​

Errors ​

Rate limits ​

User ​

Get your profile ​

Phones ​

Register a phone ​

Verify a phone ​

List your phones ​

Delete a phone ​

Subscriptions ​

Create a subscription ​

List your subscriptions ​

Delete a subscription ​

Notifications ​

List notifications ​

API keys ​

Create an API key ​

List your API keys ​

Delete an API key ​

Quickstart ​

Support ​

API Reference

Authentication

Scope and expiry

Plan limits on keys

Errors

Rate limits

User

Get your profile

Phones

Register a phone

Verify a phone

List your phones

Delete a phone

Subscriptions

Create a subscription

List your subscriptions

Delete a subscription

Notifications

List notifications

API keys

Create an API key

List your API keys

Delete an API key

Quickstart

Support