Tham khảo API

REST API của WallaWhats cho phép bạn quản lý điện thoại, đăng ký tài khoản X và lịch sử thông báo theo cách lập trình — chính xác những gì bạn có thể làm từ bảng điều khiển.

Base URL: https://api.wallawhats.com
Content type: application/json
Xác thực: API key (header)
Phiên bản: API ổn định. Các thay đổi phá vỡ tương thích được thông báo trước 30 ngày qua email đến mọi tài khoản.

Xác thực

Mọi yêu cầu phải bao gồm một API key trong header x-api-key:

bash

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

Các key được tạo trong bảng điều khiển dưới Settings → API Keys hoặc qua POST /apikeys. Tiền tố key bắt đầu bằng bws_ và dài 36 ký tự. Key chỉ được hiển thị một lần, khi tạo — nếu bạn mất một key, hãy xóa và tạo key mới.

Phạm vi và thời hạn

Một key xác thực với tư cách là người dùng đã tạo nó. Key có cùng quyền với người dùng đó và được tính vào cùng hạn mức gói.
Key có hiệu lực trong 365 ngày. Xoay vòng bằng cách tạo key mới, chuyển sang và xóa key cũ.
Key bị thiếu, sai định dạng hoặc bị thu hồi trả về 401 Unauthorized.

Giới hạn gói cho key

Gói	Số key được phép
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Cố gắng tạo nhiều hơn mức gói cho phép sẽ trả về 400 với "error": "api key limit reached".

Lỗi

Lỗi được trả về dưới dạng JSON với trường error và mã trạng thái HTTP:

json

{ "error": "phoneNumber is required" }

Trạng thái	Ý nghĩa
`400`	Tham số không hợp lệ, vượt hạn mức, hoặc vi phạm quy tắc nghiệp vụ
`401`	API key thiếu hoặc không hợp lệ
`402`	Không đủ credit để hoàn tất thao tác
`404`	Không tìm thấy tài nguyên
`500`	Lỗi máy chủ — vui lòng thử lại với exponential backoff

Giới hạn tốc độ

Mặc định: 20 yêu cầu/giây mỗi API key, bùng phát lên đến 40.
Endpoint danh sách trả về tối đa 50 mục mỗi trang; dùng con trỏ lastKey để phân trang.
Các quy tắc WAF có thể trả về 403 trên các mẫu lạm dụng. Liên hệ hỗ trợ nếu bạn bị giới hạn tốc độ ngoài dự kiến.

User

Lấy hồ sơ của bạn

GET /user/profile

Trả về hồ sơ của người dùng đã xác thực.

Phản hồi

json

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

Ví dụ

bash

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

Phones

Một phone là số WhatsApp đã xác minh có thể nhận cảnh báo. Bạn phải xác minh phone trước khi đăng ký tài khoản X cho nó.

Đăng ký phone

POST /phones

Tạo mã 6 chữ số và gửi đến số qua WhatsApp. Phone được tạo ở trạng thái pending_verification.

Yêu cầu

Field	Type	Required	Ghi chú
`phoneNumber`	string	có	Định dạng E.164, ví dụ `+84912345678`
`displayName`	string	không	Nhãn thân thiện hiển thị trong bảng điều khiển

Phản hồi

json

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

Lỗi

400 "invalid phone number format" — không phải E.164
400 "phone number limit reached" — vượt hạn mức gói (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Ví dụ

bash

curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: bws_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+84912345678", "displayName": "Work"}'

Xác minh phone

POST /phones/verify

Xác nhận phone bằng cách gửi mã 6 chữ số. Mã hết hạn sau 15 phút.

Yêu cầu

Field	Type	Required
`phoneNumber`	string (E.164)	có
`code`	string (6 chữ số)	có

Phản hồi

json

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

Lỗi

404 "phone not found"
400 "invalid code" — sai mã
400 "code expired" — quá 15 phút
400 "phone already verified"

Liệt kê các phone của bạn

GET /phones

Phản hồi

json

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

Xóa phone

DELETE /phones/{phoneNumber}

Loại bỏ phone và vô hiệu hóa mọi đăng ký nhắm đến nó. URL-encode + thành %2B.

Phản hồi

json

{ "success": true }

Ví dụ

bash

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

Subscriptions

Một subscription liên kết một tài khoản X bạn muốn theo dõi với một trong các phone đã xác minh của bạn. Khi tài khoản X đăng bài, WallaWhats gửi một cảnh báo WhatsApp đến phone đó.

Tạo subscription

POST /subscriptions

Yêu cầu

Field	Type	Required	Ghi chú
`xUsername`	string	có	1–15 ký tự, chữ cái số + gạch dưới. Tiền tố `@` được chấp nhận và loại bỏ.
`phoneNumber`	string (E.164)	có	Phải là một trong các phone đã xác minh của bạn.

Phản hồi

json

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

Lỗi

400 "invalid X username format" — regex thất bại
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — xem bảng gói bên dưới
404 "X account not found" — username không được giải quyết trên X

Giới hạn gói

Gói	Subscriptions
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Liệt kê các subscription của bạn

GET /subscriptions

Phản hồi

json

{
  "subscriptions": [ /* cùng hình dạng với phản hồi POST /subscriptions */ ],
  "count": 3
}

Xóa subscription

DELETE /subscriptions/{xUsername}

Khớp không phân biệt chữ hoa/thường trên xUsername. Loại bỏ @ trước khi gửi.

Phản hồi

json

{ "success": true }

Notifications

Mọi cảnh báo mà WallaWhats gửi đều được ghi lại ở đây, cùng với trạng thái gửi WhatsApp của nó.

Liệt kê thông báo

GET /notifications

Tham số truy vấn

Param	Type	Mô tả
`from`	number (ms epoch)	Lọc tới các thông báo được tạo tại hoặc sau thời điểm này
`to`	number (ms epoch)	Lọc tới các thông báo được tạo tại hoặc trước thời điểm này
`lastKey`	string	Con trỏ phân trang do phản hồi trước trả về

Phản hồi

json

{
  "notifications": [
    {
      "notificationId": "a1b2c3d4-...",
      "userId": "5a4cbd70-...",
      "phoneNumber": "+84912345678",
      "xUsername": "elonmusk",
      "tweetId": "1797123456789000000",
      "tweetText": "...",
      "tweetUrl": "https://x.com/elonmusk/status/...",
      "waMessageId": "wamid.HBgN...",
      "status": "delivered",
      "errorMessage": null,
      "createdAt": 1745000000000,
      "updatedAt": 1745000002000
    }
  ],
  "lastKey": "eyJOT1RJRklDQVRJT05fSUQi..."
}

Các giá trị status có thể: queued, sent, delivered, read, failed.

Kích thước trang là 50. Khi lastKey vắng mặt, bạn đã đến cuối.

API keys

Quản lý các key mà ứng dụng của bạn dùng để gọi API này.

Tạo API key

POST /apikeys

Yêu cầu

Field	Type	Required
`name`	string	không, mặc định `"Default"`

Phản hồi (201 Created)

json

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

Giá trị chỉ hiện một lần

apiKey chỉ được trả về khi tạo. Lưu ngay vào secrets manager của bạn. Các lệnh gọi sau chỉ hiện keyPrefix.

Liệt kê các API key của bạn

GET /apikeys

Phản hồi

json

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

Xóa API key

DELETE /apikeys/{keyPrefix}

Dùng keyPrefix 12 ký tự từ phản hồi danh sách — không bao giờ dùng key đầy đủ.

Phản hồi

json

{ "success": true }

Quickstart

bash

# 1. Tạo một key trong bảng điều khiển và export ra
export WALLA_API_KEY="bws_prod_..."

# 2. Đăng ký + xác minh số WhatsApp của bạn
curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+84912345678","displayName":"Mobile"}'
# -> điện thoại nhận mã WhatsApp. Gửi mã đó:
curl -X POST https://api.wallawhats.com/phones/verify \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+84912345678","code":"123456"}'

# 3. Đăng ký một tài khoản 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":"+84912345678"}'

# 4. Xem các cảnh báo đổ về
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Thế là xong — một khi tài khoản X đăng bài, cảnh báo sẽ đến điện thoại trong khoảng 10 giây.

Hỗ trợ

Câu hỏi về API, báo cáo lỗi hoặc yêu cầu tăng hạn mức: mở ticket từ tab Support trong bảng điều khiển của bạn, hoặc gửi email đến hello@support.wallawhats.com.

Tham khảo API ​

Xác thực ​

Phạm vi và thời hạn ​

Giới hạn gói cho key ​

Lỗi ​

Giới hạn tốc độ ​

User ​

Lấy hồ sơ của bạn ​

Phones ​

Đăng ký phone ​

Xác minh phone ​

Liệt kê các phone của bạn ​

Xóa phone ​

Subscriptions ​

Tạo subscription ​

Liệt kê các subscription của bạn ​

Xóa subscription ​

Notifications ​

Liệt kê thông báo ​

API keys ​

Tạo API key ​

Liệt kê các API key của bạn ​

Xóa API key ​

Quickstart ​

Hỗ trợ ​

Tham khảo API

Xác thực

Phạm vi và thời hạn

Giới hạn gói cho key

Lỗi

Giới hạn tốc độ

User

Lấy hồ sơ của bạn

Phones

Đăng ký phone

Xác minh phone

Liệt kê các phone của bạn

Xóa phone

Subscriptions

Tạo subscription

Liệt kê các subscription của bạn

Xóa subscription

Notifications

Liệt kê thông báo

API keys

Tạo API key

Liệt kê các API key của bạn

Xóa API key

Quickstart

Hỗ trợ