API 참조

WallaWhats REST API를 사용하면 전화번호, X 계정 구독, 알림 내역을 프로그래밍 방식으로 관리할 수 있습니다 — 대시보드에서 할 수 있는 모든 작업을 그대로 수행할 수 있습니다.

• 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

요금제 한도를 초과해 생성하려 하면 "error": "api key limit reached" 메시지와 함께 400이 반환됩니다.

오류

오류는 error 필드와 HTTP 상태 코드를 담은 JSON으로 반환됩니다.

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

전화번호를 삭제하고 해당 번호를 대상으로 하던 구독을 모두 비활성화합니다. +는 %2B로 URL 인코딩하세요.

응답

{ "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(ms 에포크)	이 시각 이후에 생성된 알림으로 필터
to	number(ms 에포크)	이 시각 이전에 생성된 알림으로 필터
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
}

1회성 노출

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 질문, 버그 신고, 한도 증설 요청은 대시보드의 Support 탭에서 티켓을 열거나 hello@support.wallawhats.com으로 이메일을 보내주세요.