API リファレンス

WallaWhats REST API を使うと、電話番号、X アカウントのサブスクリプション、通知履歴をプログラムから管理できます — ダッシュボードで行う操作とまったく同じことをコードから実行可能です。

Base URL: https://api.wallawhats.com
Content type: application/json
認証: API キー（ヘッダー）
バージョニング: API は安定しています。破壊的変更は 30 日前にすべてのアカウントへメールで通知されます。

認証

すべてのリクエストは x-api-key ヘッダーに API キーを含める必要があります。

bash

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 ステータスコードを含みます。

json

{ "error": "phoneNumber is required" }

ステータス	意味
`400`	パラメータが不正、割り当て超過、またはビジネスルール違反
`401`	API キーが欠落または無効
`402`	クレジット不足のため操作を完了できない
`404`	リソースが見つからない
`500`	サーバーエラー — 指数バックオフで再試行してください

レート制限

デフォルト: API キーあたり 1 秒間に 20 リクエスト、バーストは 40 まで。
リスト系エンドポイントは 1 ページあたり最大 50 件を返します。lastKey カーソルでページングしてください。
不審なパターンに対しては WAF ルールが 403 を返すことがあります。想定外のレート制限を受けた場合はサポートへご連絡ください。

User

プロフィールを取得

GET /user/profile

認証済みユーザーのプロフィールを返します。

レスポンス

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

電話番号とは、アラートを受信できる認証済みの WhatsApp 番号です。X アカウントを購読する前に、電話番号を認証する必要があります。

電話番号を登録

POST /phones

6 桁のコードを生成し、WhatsApp 経由でその番号に送信します。電話番号は pending_verification 状態で作成されます。

リクエスト

フィールド	型	必須	備考
`phoneNumber`	string	はい	E.164 形式、例: `+34612345678`
`displayName`	string	いいえ	ダッシュボードに表示される分かりやすいラベル

レスポンス

json

{ "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）

例

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

電話番号を認証

POST /phones/verify

6 桁のコードを送信して電話番号を確定します。コードは 15 分で失効します。

リクエスト

フィールド	型	必須
`phoneNumber`	string（E.164）	はい
`code`	string（6 桁）	はい

レスポンス

json

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

エラー

404 "phone not found"
400 "invalid code" — コードが不一致
400 "code expired" — 15 分を超過
400 "phone already verified"

電話番号の一覧取得

GET /phones

レスポンス

json

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

電話番号を削除

DELETE /phones/{phoneNumber}

電話番号を削除し、その番号を対象とするすべての購読を無効化します。+ は %2B に URL エンコードしてください。

レスポンス

json

{ "success": true }

例

bash

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）	はい	あなたの認証済み電話番号のいずれかを指定してください。

レスポンス

json

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

レスポンス

json

{
  "subscriptions": [ /* POST /subscriptions レスポンスと同じ構造 */ ],
  "count": 3
}

サブスクリプションを削除

DELETE /subscriptions/{xUsername}

xUsername は大文字小文字を区別しません。送信前に @ を削除してください。

レスポンス

json

{ "success": true }

Notifications

WallaWhats が配信した各アラートは、WhatsApp の配信ステータスとともにここに記録されます。

通知の一覧取得

GET /notifications

クエリパラメータ

パラメータ	型	説明
`from`	number（ミリ秒エポック）	この時刻以降に作成された通知に絞り込む
`to`	number（ミリ秒エポック）	この時刻以前に作成された通知に絞り込む
`lastKey`	string	前回のレスポンスが返したページングカーソル

レスポンス

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 が取りうる値: queued、sent、delivered、read、failed。

ページサイズは 50 です。lastKey が存在しない場合、末尾に到達しています。

API keys

この API を呼び出すアプリケーションが使用するキーを管理します。

API キーを作成

POST /apikeys

リクエスト

フィールド	型	必須
`name`	string	いいえ、デフォルトは `"Default"`

レスポンス（201 Created）

json

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

一度きりの表示

apiKey は作成時のみ返されます。直ちにシークレットマネージャーへ保存してください。以降の呼び出しでは keyPrefix のみが公開されます。

API キー一覧

GET /apikeys

レスポンス

json

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

API キーを削除

DELETE /apikeys/{keyPrefix}

リストレスポンスに含まれる 12 文字の keyPrefix を使用してください — 完全なキーは使わないでください。

レスポンス

json

{ "success": true }

クイックスタート

bash

# 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 に関する質問、バグ報告、上限引き上げのご依頼は、ダッシュボードの Support タブからチケットを作成するか、hello@support.wallawhats.com までメールでお問い合わせください。

API リファレンス ​

認証 ​

スコープと有効期限 ​

プラン別のキー上限 ​

エラー ​

レート制限 ​

User ​

プロフィールを取得 ​

Phones ​

電話番号を登録 ​

電話番号を認証 ​

電話番号の一覧取得 ​

電話番号を削除 ​

Subscriptions ​

サブスクリプションを作成 ​

サブスクリプション一覧 ​

サブスクリプションを削除 ​

Notifications ​

通知の一覧取得 ​

API keys ​

API キーを作成 ​

API キー一覧 ​

API キーを削除 ​

クイックスタート ​

サポート ​

API リファレンス

認証

スコープと有効期限

プラン別のキー上限

エラー

レート制限

User

プロフィールを取得

Phones

電話番号を登録

電話番号を認証

電話番号の一覧取得

電話番号を削除

Subscriptions

サブスクリプションを作成

サブスクリプション一覧

サブスクリプションを削除

Notifications

通知の一覧取得

API keys

API キーを作成

API キー一覧

API キーを削除

クイックスタート

サポート