이벤트 레퍼런스 v0.5.0

SDK가 수집하는 모든 이벤트 타입을 카테고리별로 정리합니다. 총 62종입니다.

상호작용 (6종)

사용자가 봇에게 보내는 입력입니다. interactionCreate 리스너로 감지하며, 건별로 즉시 큐잉됩니다.

event_type	EVENT_TYPES 키	설명
interaction_slash	interactionSlash	슬래시 명령어(Chat Input Command) 실행
interaction_button	interactionButton	버튼 클릭
interaction_select	interactionSelect	셀렉트 메뉴 선택
interaction_modal	interactionModal	모달(폼) 제출
interaction_context_menu	interactionContextMenu	사용자/메시지 컨텍스트 메뉴 실행
interaction_autocomplete	interactionAutocomplete	자동완성 요청

data 필드:

필드	타입	필수	설명
commandName	string	✅	명령어 이름 (서브커맨드 포함 전체 경로)
interactionKind	string		상호작용 종류 (1~50자)
interactionId	string		상호작용 고유 ID (최대 32자)
success	boolean		응답 성공 여부
deferred	boolean		deferReply() 사용 여부
latencyMs	number		응답 지연 시간 (0~3,600,000ms)
deferMs	number		defer까지 걸린 시간
completed	boolean		응답 완료 여부
timedOut	boolean		15초 내 미응답 시 true
shardId	integer		샤드 ID (0~32,767)
clusterId	integer		클러스터 ID (0~32,767)

자세한 내용은 상호작용 데이터 모델을 참고하세요.

작업 (22종)

봇이 Discord REST API를 호출하는 행위입니다. REST 메서드 패치로 감지하며, 건별로 즉시 큐잉됩니다.

메시지 (4종)

event_type	EVENT_TYPES 키	REST 경로	메서드
action_message_send	actionMessageSend	/channels/{id}/messages	POST
action_message_edit	actionMessageEdit	/channels/{id}/messages/{id}	PATCH
action_message_delete	actionMessageDelete	/channels/{id}/messages/{id}	DELETE
action_bulk_delete	actionBulkDelete	/channels/{id}/messages/bulk-delete	POST

채널 (2종)

event_type	EVENT_TYPES 키	REST 경로	메서드
action_channel_edit	actionChannelEdit	/channels/{id}	PATCH
action_channel_delete	actionChannelDelete	/channels/{id}	DELETE

역할 (5종)

event_type	EVENT_TYPES 키	REST 경로	메서드
action_role_add	actionRoleAdd	/guilds/{id}/members/{id}/roles/{id}	PUT
action_role_remove	actionRoleRemove	/guilds/{id}/members/{id}/roles/{id}	DELETE
action_role_create	actionRoleCreate	/guilds/{id}/roles	POST
action_role_edit	actionRoleEdit	/guilds/{id}/roles/{id}	PATCH
action_role_delete	actionRoleDelete	/guilds/{id}/roles/{id}	DELETE

멤버 (4종)

event_type	EVENT_TYPES 키	REST 경로	메서드
action_member_ban	actionMemberBan	/guilds/{id}/bans/{id}	PUT
action_member_unban	actionMemberUnban	/guilds/{id}/bans/{id}	DELETE
action_member_kick	actionMemberKick	/guilds/{id}/members/{id}	DELETE
action_member_edit	actionMemberEdit	/guilds/{id}/members/{id}	PATCH

기타 (7종)

event_type	EVENT_TYPES 키	REST 경로	메서드
action_pin	actionPin	/channels/{id}/pins/{id}	PUT
action_unpin	actionUnpin	/channels/{id}/pins/{id}	DELETE
action_react	actionReact	/channels/{id}/messages/{id}/reactions/...	PUT
action_thread_create	actionThreadCreate	/channels/{id}/threads	POST
action_permission_edit	actionPermissionEdit	/channels/{id}/permissions/{id}	PUT
action_invite_create	actionInviteCreate	/channels/{id}/invites	POST
action_voice_session	actionVoiceSession	(음성 상태 추적)	--

일반 작업 data 필드:

필드	타입	설명
shardId	integer	샤드 ID (0~32,767)
clusterId	integer	클러스터 ID (0~32,767)

action_voice_session data 필드:

필드	타입	필수	설명
durationMs	integer	✅	세션 지속 시간 (ms)
peakListeners	integer		최대 청취자 수 (봇 제외)
startedTs	string		세션 시작 시각 (ISO-8601)
shardId	integer		샤드 ID
clusterId	integer		클러스터 ID

자세한 내용은 작업 데이터 모델을 참고하세요.

게이트웨이 이벤트 (24종)

Discord 게이트웨이에서 발생하는 서버 활동입니다. 60초 카운터로 집계하여 전송됩니다.

event_type	EVENT_TYPES 키	discord.js 이벤트	필요 인텐트
event_member_join	eventMemberJoin	guildMemberAdd	GuildMembers
event_member_leave	eventMemberLeave	guildMemberRemove	GuildMembers
event_member_update	eventMemberUpdate	guildMemberUpdate	GuildMembers
event_message_create	eventMessageCreate	messageCreate	GuildMessages
event_message_update	eventMessageUpdate	messageUpdate	GuildMessages
event_message_delete	eventMessageDelete	messageDelete	GuildMessages
event_channel_create	eventChannelCreate	channelCreate	Guilds
event_channel_update	eventChannelUpdate	channelUpdate	Guilds
event_channel_delete	eventChannelDelete	channelDelete	Guilds
event_role_create	eventRoleCreate	roleCreate	Guilds
event_role_update	eventRoleUpdate	roleUpdate	Guilds
event_role_delete	eventRoleDelete	roleDelete	Guilds
event_ban_add	eventBanAdd	guildBanAdd	GuildModeration
event_ban_remove	eventBanRemove	guildBanRemove	GuildModeration
event_reaction_add	eventReactionAdd	messageReactionAdd	GuildMessageReactions
event_reaction_remove	eventReactionRemove	messageReactionRemove	GuildMessageReactions
event_voice_state	eventVoiceState	voiceStateUpdate	Guilds
event_thread_create	eventThreadCreate	threadCreate	Guilds
event_thread_update	eventThreadUpdate	threadUpdate	Guilds
event_thread_delete	eventThreadDelete	threadDelete	Guilds
event_invite_create	eventInviteCreate	inviteCreate	Guilds
event_invite_delete	eventInviteDelete	inviteDelete	Guilds
event_typing_start	eventTypingStart	typingStart	GuildMessageTyping
event_presence_update	eventPresenceUpdate	presenceUpdate	GuildPresences

참고

GuildMembers와 GuildPresences는 특권 인텐트입니다. Discord Developer Portal에서 활성화해야 합니다.

data 필드:

필드	타입	필수	설명
count	integer	✅	집계 기간(60초) 동안 발생한 건수

자세한 내용은 이벤트 데이터 모델을 참고하세요.

오류 (2종)

event_type	EVENT_TYPES 키	감지 방식
command_error	commandError	상호작용 응답 메서드(reply 등) reject/throw 시
error	error	captureError() 호출 또는 autoCapturePromiseRejections

command_error data 필드:

필드	타입	필수	설명
name	string	✅	오류 이름 (1~200자)
message	string	✅	오류 메시지 (최대 2 KiB)
stack	string		스택 트레이스 (최대 8 KiB)
commandName	string		관련 명령어 이름
interactionKind	string		상호작용 종류
interactionId	string		원래 상호작용 이벤트와 연결하는 ID
phase	string		오류 발생 단계 (최대 50자)
shardId	integer		샤드 ID
clusterId	integer		클러스터 ID

error data 필드:

필드	타입	필수	설명
name	string	✅	오류 이름 (1~200자)
message	string	✅	오류 메시지 (최대 2 KiB)
stack	string		스택 트레이스 (최대 8 KiB)
source	string		오류 출처 (최대 50자)
shardId	integer		샤드 ID
clusterId	integer		클러스터 ID

서버 (2종)

event_type	EVENT_TYPES 키	감지 방식
guild_join	guildJoin	guildCreate (unavailable 제외)
guild_leave	guildLeave	guildDelete (unavailable 제외)

unavailable 필터링

Discord 장애로 서버가 일시적으로 unavailable 상태가 되면 guildDelete 이벤트가 발생합니다. SDK는 available === false인 경우를 무시하여 실제 탈퇴만 기록합니다.

data 필드:

필드	타입	설명
memberCount	integer	서버 멤버 수
guildName	string	서버 이름 (최대 100자)
locale	string	서버 로케일 (최대 10자)
shardId	integer	샤드 ID
clusterId	integer	클러스터 ID

샤드 생명주기 (4종)

event_type	EVENT_TYPES 키	discord.js 이벤트
shard_ready	shardReady	shardReady
shard_disconnect	shardDisconnect	shardDisconnect
shard_resume	shardResume	shardResume
shard_reconnecting	shardReconnecting	shardReconnecting

data 필드:

필드	타입	설명
shardId	integer	샤드 ID (0~32,767)
clusterId	integer	클러스터 ID (0~32,767)
closeCode	integer	종료 코드 (0~65,535, disconnect 시에만)
replayedEvents	integer	재생된 이벤트 수 (resume 시에만)

스냅샷 (3종)

스냅샷은 events 테이블에 저장되지 않으며, 할당량에 포함되지 않습니다.

heartbeat

snapshotIntervalMs 주기(기본 60초)마다 수집되는 봇 상태 스냅샷입니다.

필드	타입	설명
guildCount	integer	캐시된 서버 수
wsPingMs	number	WebSocket 핑 (ms)
memoryMb	number	메모리 사용량 (MB)
cpuPercent	number	CPU 사용률 (0~100)
voiceConnections	integer	활성 음성 연결 수
eventLoopP95Ms	number	이벤트 루프 P95 (ms)
gatewayEvents	integer	윈도우 내 게이트웨이 이벤트 수
apiRequests	integer	윈도우 내 REST API 요청 수
api429Global	integer	글로벌 429 횟수
api429Bucket	integer	버킷 429 횟수
apiInvalid	integer	잘못된 API 요청 수
botUserId	string	봇 사용자 ID
botAvatarHash	string	봇 아바타 해시
shardId	integer	샤드 ID
clusterId	integer	클러스터 ID

guild_snapshot

snapshotIntervalMs 주기마다 캐시된 각 서버의 상태를 기록합니다.

필드	타입	설명
memberCount	integer	서버 멤버 수
onlineCount	integer	온라인 멤버 수 (GuildPresences 인텐트 필요)
guildName	string	서버 이름 (최대 100자)
locale	string	서버 로케일 (최대 10자)
shardId	integer	샤드 ID
clusterId	integer	클러스터 ID

api_routes_snapshot

5분 주기로 상위 10개 API 라우트 사용 통계를 수집합니다 (유휴 시 건너뜀).

필드	타입	필수	설명
routes	array	✅	상위 10개 라우트 배열
routes[].route	string	✅	API 라우트 경로 (스노우플레이크 정규화, 1~120자)
routes[].count	integer	✅	호출 횟수
shardId	integer		샤드 ID
clusterId	integer		클러스터 ID

커스텀 (1종)

event_type	EVENT_TYPES 키	감지 방식
custom	custom	track(name, props) 호출

data 필드:

필드	타입	필수	설명
name	string	✅	이벤트 이름 (최대 256바이트 UTF-8)
props	object		속성 (최대 50키, 키당 100자, 전체 8 KiB)
shardId	integer		샤드 ID
clusterId	integer		클러스터 ID

disabledEvents로 비활성화할 수 없습니다. 자세한 사용법은 커스텀 이벤트를 참고하세요.

레거시 이벤트 이름

v0.5.0에서 이름이 변경된 이벤트입니다. 이전 이름도 하위 호환을 위해 지원됩니다.

이전 이름	현재 이름	EVENT_TYPES 키
message_sent	action_message_send	messageSent (deprecated) → actionMessageSend
voice_session	action_voice_session	voiceSession (deprecated) → actionVoiceSession

데이터 보호 요약

항목	제한
문자열 속성	개당 최대 4 KiB
이벤트 data 전체	최대 16 KiB
오류 name	최대 200자
오류 message	최대 2 KiB
오류 stack	최대 8 KiB
중첩 깊이	최대 8단계
배열 항목	최대 100개
객체 키	최대 100개
순환 참조	자동 제거
직렬화 불가능 값	자동 제거 (함수, Symbol, undefined)