권한 고르기
권한은 봇이 DJ 에게 요청하는 동의 단위예요. 앱에 등록한 권한만 요청할 수 있고, DJ 가 허용한 권한만 실제로 동작해요.
각 권한이 어느 엔드포인트로 이어지는지는 아래 표의 명세 열에서 바로 열려요. 이 페이지는 무엇을 고를지 정하는 데 써요.
권한 목록
| 스코프 | DJ 에게 보이는 이름 | 무엇을 주나요 | 명세 |
|---|---|---|---|
me.read | 나를 가리키는 식별자 보기 | 이 토큰이 가리키는 DJ 의 암호화 식별자 — 어느 봇이든 기본으로 필요해요 | DJ 식별자 조회 |
live.read | 내 방송 정보 보기 | 방송 제목 · 시작/종료 시각 · 청취자 수 · 인사말 · 카테고리 · 채팅 얼림 상태 | 현재 방송 조회 |
listeners.read | 내 방송의 청취자 목록 보기 | 지금 방에 있는 청취자의 id · 닉네임 · 구독 여부 | 청취자 목록 조회 |
fans.read | 내 방송의 팬 랭킹 보기 | 후원이 많은 순 청취자 순위 | 팬 랭킹 조회 |
events.chat | 내 방송의 채팅 보기 | 청취자 채팅과 DJ 퀵메시지를 실시간으로 | 이벤트 스트림 · chat |
events.presence | 내 방송에 누가 들어오는지 보기 | 청취자의 방송 입장을 실시간으로 | 이벤트 스트림 · presence |
events.like | 내 방송의 하트 보기 | 청취자가 보낸 하트를 실시간으로 | 이벤트 스트림 · like |
events.donation | 내 방송의 후원을 실시간으로 보기 | 후원자 · 총 스푼 · 도네이션 메시지를 실시간으로 | 이벤트 스트림 · donation |
donations.read | 내 방송의 후원 내역 보기 | 현재 방송에서 받은 후원 내역 조회 — 목록 · 집계 · 스티커 구분 | 후원 내역 조회 |
events.follow | 내 방송의 새 팔로우 보기 | 방송 중 새 팔로우를 실시간으로 — 방송당 첫 팔로우만 | 이벤트 스트림 · follow |
chat.send | 내 방송에 봇 이름으로 채팅 보내기 | 봇 계정 이름으로 발화 | 채팅 보내기 |
dj.follow | 봇 계정이 나를 팔로우하기 | 봇 계정으로 DJ 를 팔로우. 고정 매니저로 지정받기 전에 필요해요 | DJ 팔로우 |
어떤 조합이 필요한가요
봇이 실제로 쓰는 것만 요청해요. 동의 화면에 권한이 많을수록 DJ 가 허용을 망설여요.
| 만들려는 봇 | 필요한 권한 |
|---|---|
| 채팅에 반응해 답하는 봇 | events.chat · chat.send |
| 방송 시작·종료에 맞춰 안내하는 봇 | live.read · chat.send |
| 입장한 청취자를 환영하는 봇 | events.presence · chat.send · dj.follow (DJ 의 고정 매니저 지정 필요. 그 전에 봇 계정이 DJ 를 팔로우하는 데 dj.follow 를 써요) |
| 후원에 감사 인사를 보내는 봇 | events.donation · chat.send |
| 놓친 후원을 복구·집계하는 봇 | donations.read · events.donation |
| 새 팬에게 감사 인사를 보내는 봇 | events.follow · chat.send (DJ 의 고정 매니저 지정 필요) |
| 하트를 집계해 목표를 알리는 봇 | events.like · chat.send |
| 청취자 중에서 추첨하는 봇 | listeners.read · chat.send |
| 팬 랭킹을 읽어 주는 봇 | fans.read · chat.send |
| 출석·랭킹을 집계하는 봇 | events.chat · events.presence · live.read |
권한을 요청하는 방법
사용자 동의 받기 의 scope 파라미터에
공백으로 이어서 적어요. 주소에 실을 때는 %20 으로 인코딩해요.
&scope=me.read%20events.chat%20events.presence%20chat.send
동의는 쌓여요. 나중에 권한을 추가하려면 늘어난 권한으로 다시 동의 화면을 띄우면 되고, DJ 는 새로 요청한 권한만 보게 돼요.
발급받은 토큰의 scope 는 그 시점 DJ 의 동의 기준이에요. 갱신할 때마다 확인해요 —
자세한 내용은 토큰 에 있어요.
알아둘 것 두 가지
이벤트 권한은 한 연결을 나눠 써요
events. 로 시작하는 다섯 권한은 연결 하나를 공유해요.
- 그중 하나라도 있으면 이벤트 스트림 이 열려요.
- 동의받지 않은 이벤트는 걸러져요. 연결은 정상인데 그 이벤트만 오지 않아요.
- 하나도 없으면
403이에요.
동의만으로는 안 되는 권한이 있어요
events.presence 와 events.follow 는 봇이 매니저여야 동작해요. 운영할 봇은 DJ 가 고정 매니저로 지정하는 걸 권장하고,
고정 매니저를 받으려면 봇 계정이 DJ 를 먼저 팔로우해야 해요. dj.follow 를 받아
DJ 팔로우 를 부르면 되고, 봇 계정으로 스푼 앱에서 직접 팔로우해도 돼요.
동의는 받았는데 지정이 없으면 오류가 나지 않아요. 스트림은 200 으로 열리고 chat 도
잘 오는데 presence 와 follow 만 한 건도 오지 않아서 원인을 찾기 어려워요. 방송 서버가
입장 · 팔로우 알림을 매니저 등급으로 발행하기 때문이에요.
지정 절차는 이벤트 스트림 에 있어요.