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。