API 參考

WallaWhats REST API 讓您能以程式化方式管理手機號碼、X 帳號訂閱和通知歷史紀錄 —— 凡是可在控制台完成的操作，都能透過 API 達成。

• Base URL: https://api.wallawhats.com
• Content type: application/json
• 認證方式: API 金鑰（請求標頭）
• 版本策略: API 保持穩定。所有破壞性變更都會提前 30 天透過電子郵件通知每位使用者。

認證

每個請求都必須在 x-api-key 請求標頭中附帶 API 金鑰：

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

金鑰可在控制台的 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" }

狀態碼	含義
400	參數無效、配額超限或違反業務規則
401	API 金鑰缺少或無效
402	點數不足，無法完成操作
404	找不到資源
500	伺服器錯誤 —— 請使用指數退避策略重試

速率限制

• 預設: 每個 API 金鑰每秒 20 個請求，峰值 40。
• 列表端點每頁最多回傳 50 筆，請使用 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

手機號碼是一個可接收提醒的已驗證 WhatsApp 號碼。訂閱任何 X 帳號前，您必須先完成手機驗證。

註冊手機號碼

POST /phones

產生一組 6 位數驗證碼並透過 WhatsApp 發送至該號碼。此時手機號碼處於 pending_verification 狀態。

請求

欄位	類型	必填	備註
phoneNumber	string	是	E.164 格式，例如 +34612345678
displayName	string	否	控制台中顯示的友善標籤

回應

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

錯誤

• 400 "invalid phone number format" —— 不符合 E.164 格式
• 400 "phone number limit reached" —— 超過方案允許（Free/Pro/Pro+ 1 組，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

訂閱會將您想監控的 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" —— 不符合正規表示式
• 400 "phone not found" / "phone not verified"
• 400 "subscription limit reached" —— 見下方方案表
• 404 "X account not found" —— 使用者名稱在 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

查詢參數

參數	類型	說明
from	number（毫秒時間戳）	篩選此時間或之後建立的通知
to	number（毫秒時間戳）	篩選此時間或之前建立的通知
lastKey	string	前次回應回傳的分頁游標

回應

{
  "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 金鑰

POST /apikeys

請求

欄位	類型	必填
name	string	否，預設為 "Default"

回應（201 Created）

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

僅顯示一次

apiKey 僅在建立時回傳一次。請立即將其儲存到您的密碼管理器。後續呼叫只會暴露 keyPrefix。

列出您的 API 金鑰

GET /apikeys

回應

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

刪除 API 金鑰

DELETE /apikeys/{keyPrefix}

請使用列表回應中的 12 字元 keyPrefix —— 切勿使用完整金鑰。

回應

{ "success": true }

---

快速上手

# 1. 在控制台建立金鑰並匯出
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 相關問題、Bug 回報或配額提升申請：請在控制台的 Support 頁籤提交工單，或寄信至 hello@support.wallawhats.com。