API रेफ़रेंस

WallaWhats REST API आपको programmatically फ़ोन, X अकाउंट subscriptions और notification इतिहास प्रबंधित करने देता है — ठीक वही जो आप अन्यथा dashboard से करेंगे।

Base URL: https://api.wallawhats.com
Content type: application/json
Authentication: API key (header)
Versioning: API स्थिर है। Breaking changes प्रत्येक अकाउंट को ईमेल के माध्यम से 30 दिन पहले घोषित किए जाते हैं।

Authentication

हर request में x-api-key header में एक API key शामिल होनी चाहिए:

bash

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

Keys dashboard में Settings → API Keys के अंतर्गत या POST /apikeys के माध्यम से बनाई जाती हैं। एक key prefix bws_ से शुरू होता है और 36 अक्षर लंबा होता है। Keys केवल एक बार, बनाते समय दिखाई जाती हैं — यदि आप एक खो देते हैं, तो इसे delete करें और एक नई बनाएँ।

Scope और expiry

एक key उस उपयोगकर्ता के रूप में authenticate करती है जिसने इसे बनाया है। इसकी उसी उपयोगकर्ता के समान permissions हैं और उसी plan quotas के विरुद्ध गिनी जाती है।
Keys 365 दिनों के लिए मान्य हैं। एक नई key बनाकर, उस पर switch करके, और पुरानी को delete करके rotate करें।
गुम, गलत format या revoked keys 401 Unauthorized लौटाती हैं।

Keys पर plan सीमाएँ

प्लान	अनुमत keys
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

अपने plan की अनुमति से अधिक बनाने का प्रयास 400 के साथ "error": "api key limit reached" लौटाता है।

त्रुटियाँ

त्रुटियाँ error field और HTTP status code के साथ JSON के रूप में लौटाई जाती हैं:

json

{ "error": "phoneNumber is required" }

Status	अर्थ
`400`	अमान्य parameters, quota पार, या business-rule उल्लंघन
`401`	गुम या अमान्य API key
`402`	ऑपरेशन पूरा करने के लिए पर्याप्त credits नहीं
`404`	Resource नहीं मिला
`500`	Server त्रुटि — कृपया exponential backoff के साथ पुनः प्रयास करें

Rate limits

Default: प्रति API key 20 requests/सेकंड, 40 तक bursting।
List endpoints प्रति page अधिकतम 50 items लौटाते हैं; paginate करने के लिए lastKey cursor का उपयोग करें।
WAF rules abusive patterns पर 403 लौटा सकते हैं। यदि आप अप्रत्याशित रूप से rate-limited हो रहे हैं तो support से संपर्क करें।

User

अपना profile प्राप्त करें

GET /user/profile

Authenticated उपयोगकर्ता का profile लौटाता है।

Response

json

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

उदाहरण

bash

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

Phones

एक phone एक verified WhatsApp नंबर है जो alerts प्राप्त कर सकता है। X अकाउंट subscribe करने से पहले आपको phone verify करना होगा।

Phone register करें

POST /phones

एक 6-digit code उत्पन्न करता है और WhatsApp के माध्यम से नंबर पर भेजता है। Phone pending_verification state में बनाया जाता है।

Request

Field	Type	आवश्यक	नोट्स
`phoneNumber`	string	हाँ	E.164 format, जैसे `+34612345678`
`displayName`	string	नहीं	Dashboard में दिखाया जाने वाला friendly label

Response

json

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

त्रुटियाँ

400 "invalid phone number format" — E.164 नहीं
400 "phone number limit reached" — plan की अनुमति से अधिक (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

उदाहरण

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

Phone verify करें

POST /phones/verify

6-digit code submit करके phone की पुष्टि करता है। Codes 15 मिनट के बाद expire होते हैं।

Request

Field	Type	आवश्यक
`phoneNumber`	string (E.164)	हाँ
`code`	string (6 digits)	हाँ

Response

json

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

त्रुटियाँ

404 "phone not found"
400 "invalid code" — गलत code
400 "code expired" — 15 मिनट से अधिक पुराना
400 "phone already verified"

अपने phones list करें

GET /phones

Response

json

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

Phone delete करें

DELETE /phones/{phoneNumber}

Phone हटाता है और इसे target करने वाले किसी भी subscriptions को निष्क्रिय करता है। + को %2B के रूप में URL-encode करें।

Response

json

{ "success": true }

उदाहरण

bash

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

Subscriptions

एक subscription उस X अकाउंट को आपके verified phones में से एक से जोड़ता है जिसे आप monitor करना चाहते हैं। जब X अकाउंट पोस्ट करता है, WallaWhats उस phone पर एक WhatsApp alert भेजता है।

Subscription बनाएँ

POST /subscriptions

Request

Field	Type	आवश्यक	नोट्स
`xUsername`	string	हाँ	1–15 chars, alphanumeric + underscore। `@` prefix स्वीकार किया जाता है और हटा दिया जाता है।
`phoneNumber`	string (E.164)	हाँ	आपके verified phones में से एक होना चाहिए।

Response

json

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

त्रुटियाँ

400 "invalid X username format" — regex fail
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — नीचे plan table देखें
404 "X account not found" — username X पर resolve नहीं होता

Plan सीमाएँ

प्लान	Subscriptions
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

अपने subscriptions list करें

GET /subscriptions

Response

json

{
  "subscriptions": [ /* POST /subscriptions response की तरह ही आकार */ ],
  "count": 3
}

Subscription delete करें

DELETE /subscriptions/{xUsername}

xUsername पर case-insensitive match। भेजने से पहले @ हटाएँ।

Response

json

{ "success": true }

Notifications

WallaWhats द्वारा delivered हर alert यहाँ log किया जाता है, इसके WhatsApp delivery status के साथ।

Notifications list करें

GET /notifications

Query parameters

Param	Type	विवरण
`from`	number (ms epoch)	इस समय या उसके बाद बनाए गए notifications तक filter करें
`to`	number (ms epoch)	इस समय या उससे पहले बनाए गए notifications तक filter करें
`lastKey`	string	पिछली response द्वारा लौटाया गया pagination cursor

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

संभावित status values: queued, sent, delivered, read, failed।

Page size 50 है। जब lastKey अनुपस्थित हो, तो आप अंत तक पहुँच गए हैं।

API keys

उन keys को प्रबंधित करें जिनका उपयोग आपके applications इस API को call करने के लिए करते हैं।

API key बनाएँ

POST /apikeys

Request

Field	Type	आवश्यक
`name`	string	नहीं, default `"Default"`

Response (201 Created)

json

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

एक-बार-दिखाया जाने वाला मान

apiKey केवल बनाते समय लौटाया जाता है। इसे तुरंत अपने secrets manager में store करें। बाद के calls केवल keyPrefix उजागर करते हैं।

अपनी API keys list करें

GET /apikeys

Response

json

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

API key delete करें

DELETE /apikeys/{keyPrefix}

List response से 12-अक्षर keyPrefix का उपयोग करें — कभी भी पूर्ण key नहीं।

Response

json

{ "success": true }

Quickstart

bash

# 1. Dashboard में एक key बनाएँ और export करें
export WALLA_API_KEY="bws_prod_..."

# 2. अपना WhatsApp नंबर register + verify करें
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"}'
# -> phone को WhatsApp code प्राप्त होता है। इसे submit करें:
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 अकाउंट को subscribe करें
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. Alerts आते देखें
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

बस इतना ही — एक बार X अकाउंट पोस्ट करता है, alert ~10 सेकंड में phone पर पहुँच जाता है।

Support

API प्रश्न, bug reports, या quota-increase requests: अपने dashboard में Support tab से एक ticket खोलें, या hello@support.wallawhats.com पर ईमेल करें।

API रेफ़रेंस ​

Authentication ​

Scope और expiry ​

Keys पर plan सीमाएँ ​

त्रुटियाँ ​

Rate limits ​

User ​

अपना profile प्राप्त करें ​

Phones ​

Phone register करें ​

Phone verify करें ​

अपने phones list करें ​

Phone delete करें ​

Subscriptions ​

Subscription बनाएँ ​

अपने subscriptions list करें ​

Subscription delete करें ​

Notifications ​

Notifications list करें ​

API keys ​

API key बनाएँ ​

अपनी API keys list करें ​

API key delete करें ​

Quickstart ​

Support ​

API रेफ़रेंस

Authentication

Scope और expiry

Keys पर plan सीमाएँ

त्रुटियाँ

Rate limits

User

अपना profile प्राप्त करें

Phones

Phone register करें

Phone verify करें

अपने phones list करें

Phone delete करें

Subscriptions

Subscription बनाएँ

अपने subscriptions list करें

Subscription delete करें

Notifications

Notifications list करें

API keys

API key बनाएँ

अपनी API keys list करें

API key delete करें

Quickstart

Support