작업 22종
봇이 Discord REST API를 호출하는 행위 22종의 감지 방식과 수집 필드를 설명합니다.
감지 방식
SDK는 client.rest의 post/patch/put/delete 메서드를 패치하여, 각 HTTP 요청의 URL 패턴을 분석합니다. URL이 미리 정의된 패턴과 일치하면 해당 작업 타입의 이벤트를 생성합니다.
interaction.reply()는 감지되지 않습니다
interaction.reply(), interaction.deferReply() 등은 Discord 웹훅 경로(/webhooks/...)를 사용합니다. SDK는 웹훅 경로를 패치하지 않으므로 이 호출들은 작업으로 감지되지 않습니다.
봇이 직접 channel.send()로 메시지를 보내는 경우만 action_message_send로 감지됩니다.
작업 타입 목록
메시지 (4종)
| event_type | 설명 | REST 경로 | HTTP 메서드 |
|---|---|---|---|
action_message_send | 메시지 전송 | /channels/{id}/messages | POST |
action_message_edit | 메시지 수정 | /channels/{id}/messages/{id} | PATCH |
action_message_delete | 메시지 삭제 | /channels/{id}/messages/{id} | DELETE |
action_bulk_delete | 메시지 일괄 삭제 | /channels/{id}/messages/bulk-delete | POST |
채널 (2종)
| event_type | 설명 | REST 경로 | HTTP 메서드 |
|---|---|---|---|
action_channel_edit | 채널 수정 | /channels/{id} | PATCH |
action_channel_delete | 채널 삭제 | /channels/{id} | DELETE |
역할 (5종)
| event_type | 설명 | REST 경로 | HTTP 메서드 |
|---|---|---|---|
action_role_add | 멤버에게 역할 부여 | /guilds/{id}/members/{id}/roles/{id} | PUT |
action_role_remove | 멤버에게서 역할 회수 | /guilds/{id}/members/{id}/roles/{id} | DELETE |
action_role_create | 역할 생성 | /guilds/{id}/roles | POST |
action_role_edit | 역할 수정 | /guilds/{id}/roles/{id} | PATCH |
action_role_delete | 역할 삭제 | /guilds/{id}/roles/{id} | DELETE |
멤버 (4종)
| event_type | 설명 | REST 경로 | HTTP 메서드 |
|---|---|---|---|
action_member_ban | 멤버 차단 | /guilds/{id}/bans/{id} | PUT |
action_member_unban | 멤버 차단 해제 | /guilds/{id}/bans/{id} | DELETE |
action_member_kick | 멤버 추방 | /guilds/{id}/members/{id} | DELETE |
action_member_edit | 멤버 수정 (닉네임, 타임아웃 등) | /guilds/{id}/members/{id} | PATCH |
기타 (7종)
| event_type | 설명 | REST 경로 | HTTP 메서드 |
|---|---|---|---|
action_pin | 메시지 고정 | /channels/{id}/pins/{id} | PUT |
action_unpin | 메시지 고정 해제 | /channels/{id}/pins/{id} | DELETE |
action_react | 리액션 추가 | /channels/{id}/messages/{id}/reactions/{emoji}/@me | PUT |
action_thread_create | 스레드 생성 | /channels/{id}/threads | POST |
action_permission_edit | 채널 권한 수정 | /channels/{id}/permissions/{id} | PUT |
action_invite_create | 초대 링크 생성 | /channels/{id}/invites | POST |
action_voice_session | 음성 세션 종료 | (REST가 아닌 음성 상태 추적) | -- |
action_voice_session은 특별합니다
action_voice_session은 REST 메서드 패치가 아닌, 봇의 음성 연결 상태를 추적하여 수집됩니다. 봇이 음성 채널에서 퇴장하거나 다른 채널로 이동할 때, 세션의 durationMs(지속 시간)와 peakListeners(최대 청취자 수)가 기록됩니다. 다른 사용자의 음성 활동은 수집하지 않습니다.
수집 필드
공통 필드 (envelope)
| 필드 | 수집 여부 | 설명 |
|---|---|---|
guild_id | 일부 ✅ | URL에서 추출 (guild 경로 포함 시), 또는 채널 캐시에서 조회 |
channel_id | 일부 ✅ | URL에서 추출 (channel 경로 포함 시) |
user_id | ❌ | 작업의 대상 사용자는 수집하지 않음 |
참고
모든 작업에 guild_id와 channel_id가 포함되는 것은 아닙니다.
- guild 경로 (
/guilds/{id}/...):guild_id있음,channel_id없음 - channel 경로 (
/channels/{id}/...):channel_id있음,guild_id는 채널 캐시에서 조회 (DM 채널 등 캐시에 없으면null) action_voice_session: 음성 채널의guild_id와channel_id모두 포함
data 필드 (일반 작업)
| 필드 | 타입 | 설명 |
|---|---|---|
shardId | integer | 샤드 ID (0 ~ 32,767) |
clusterId | integer | 클러스터 ID (0 ~ 32,767, 설정 시에만) |
data 필드 (action_voice_session)
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
durationMs | integer | ✅ | 세션 지속 시간 (ms) |
peakListeners | integer | 최대 청취자 수 (봇 제외) | |
startedTs | string | 세션 시작 시각 (ISO-8601) | |
shardId | integer | 샤드 ID | |
clusterId | integer | 클러스터 ID |
레거시 이벤트 이름
v0.5.0부터 일부 이벤트 이름이 변경되었습니다. 이전 이름도 하위 호환을 위해 계속 지원됩니다.
| 이전 이름 | 현재 이름 | 비고 |
|---|---|---|
message_sent | action_message_send | 작업 카테고리로 재분류 |
voice_session | action_voice_session | 작업 카테고리로 재분류 |
참고
disabledEvents 옵션에서 이전 이름과 현재 이름 모두 사용할 수 있습니다. 새 프로젝트에서는 현재 이름을 사용하세요.
대시보드에서 확인
작업 데이터는 보고서의 활동 카테고리에서 확인합니다.
- 메시지:
action_message_send등 메시지 관련 작업 추이 - 음성:
action_voice_session의 세션 수, 총 시간, 평균 청취자 수
탐색(Explore)에서 event_type = action_* 필터로 특정 작업 타입을 분석할 수 있습니다.