빠른 시작

처음 연동하는 앱 개발자를 위한 튜토리얼입니다. 앱을 등록하고 스트리머의 동의를 받아 토큰을 발급받은 뒤, 첫 API 호출과 실시간 이벤트 수신까지 순서대로 따라 합니다.

준비물

예제의 경로 앞에는 잼쿠봇 사이트의 기본 주소를 붙입니다. YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, RECEIVED_CODE, ACCESS_TOKEN 같은 대문자 값은 발급받은 값으로 바꿉니다.

1. 앱 등록

1. 대시보드 → 개발자센터(API)를 열고 내 애플리케이션의 + 새 앱을 누릅니다.
2. 앱 이름과 로그인 리디렉션 URL(예: https://myapp.example.com/callback)을 적습니다.
3. API Scopes에서 이 튜토리얼에 쓰는 명령어 조회(commands:read)와 실시간 이벤트 구독(events:subscribe)을 고르고 등록을 누릅니다.
4. 화면에 나온 client_id 와 client_secret 을 앱 서버에 보관합니다.

입력 규칙과 화면 설명은 앱 등록·관리에 있습니다.

2. 스트리머 동의 받기

연결할 스트리머의 브라우저를 인가 주소로 보냅니다. state 에는 앱이 만든 임의 값을 넣고 기억해 둡니다.

GET /developers/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fmyapp.example.com%2Fcallback&scope=commands:read%20events:subscribe&state=RANDOM_STATE

스트리머가 치지직으로 로그인하고 동의 화면에서 허용하기를 누르면 리디렉션 URL 로 인가 코드가 돌아옵니다. 거부하면 code 대신 error=access_denied 가 붙습니다.

https://myapp.example.com/callback?code=RECEIVED_CODE&state=RANDOM_STATE

state 가 보낸 값과 같은지 먼저 확인한 뒤 다음 단계로 갑니다. 파라미터와 오류는 인가 요청을 참고하세요.

3. 코드를 토큰으로 교환

앱 서버에서 인가 코드를 토큰으로 바꿉니다. 코드는 5분 안에 한 번만 쓸 수 있습니다.

POST /developers/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=RECEIVED_CODE&redirect_uri=https%3A%2F%2Fmyapp.example.com%2Fcallback&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "commands:read events:subscribe"
}

액세스 토큰은 2시간, 리프레시 토큰은 30일 동안 쓸 수 있습니다. 두 토큰을 함께 저장하고 만료 전에 리프레시 토큰으로 갱신합니다. 방법은 코드를 토큰으로 교환과 토큰 갱신에 있습니다.

토큰 응답에는 채널 정보가 없습니다. 받은 토큰으로 토큰 정보 (me)를 부르면 어느 채널의 토큰인지 확인할 수 있습니다.

GET /api/v1/developer/me
Authorization: Bearer ACCESS_TOKEN

{"streamer_uid": "0123456789abcdef0123456789abcdef", "nickname": "잼쿠", "scopes": ["commands:read", "events:subscribe"], "expires_at": 1791234567}

4. API 호출

액세스 토큰을 Authorization 헤더에 넣어 명령어 목록을 조회합니다.

GET /api/v1/developer/commands
Authorization: Bearer ACCESS_TOKEN

[
  {
    "id": 12,
    "cmd_index": 0,
    "command": "!인사",
    "response": "안녕하세요!",
    "response_use_point_fail": "",
    "point": 0,
    "cooltime": 10,
    "user_cooltime": 0,
    "live_only": false,
    "notice_on_staff": false,
    "user_daily_limit": 0,
    "total_daily_limit": 0,
    "total_used_count": 42,
    "total_daily_used_count": 3,
    "is_attendance": false,
    "activate": true
  }
]

토큰은 동의한 스트리머 채널의 데이터만 다룹니다. API 주소에 다른 채널의 UID 를 넣어 접근하는 방식이 아니며, 채널마다 그 스트리머의 동의와 토큰이 따로 필요합니다. 스트리머가 연결을 해제하면 그 채널의 토큰은 바로 쓸 수 없게 됩니다.

API 마다 필요한 권한은 Scope 별 API, 응답 필드는 명령어 목록 조회, 오류 처리는 공통 사항에 있습니다.

5. 실시간 이벤트 받기

events:subscribe 권한이 있으면 WebSocket 으로 채널 이벤트를 받습니다. 사이트 주소가 https:// 면 wss:// 로 연결합니다.

WS /api/v1/developer/ws?access_token=ACCESS_TOKEN

← {"type": "connected", "streamer_uid": "STREAMER_UID", "events": ["attendance", "command", "optional_feature", "overlay_text", "point_use", "run_roulette", "run_roulette2"]}
← {"streamer_uid": "STREAMER_UID", "event": {"type": "command", "used_command": "!인사", "...": "..."}}
→ {"type": "ping"}
← {"type": "pong"}

• 연결 직후 오는 connected 의 streamer_uid 가 이 토큰이 연결된 채널이고, events 가 받을 수 있는 이벤트입니다. 이 튜토리얼은 commands:read 도 받았으므로 명령어 이벤트까지 옵니다.
• 이벤트는 채널에서 실제로 일이 생겨야 옵니다. 채팅에 명령어를 쳐서 확인해 보세요.
• 주기적으로 {"type": "ping"} 을 보냅니다. 토큰이 무효가 되면 연결이 4401 로 닫히니 갱신한 토큰으로 다시 연결합니다.

자세한 내용은 WebSocket 이벤트를 참고하세요.

다음 단계