상호작용 6종
사용자가 봇에게 보내는 입력 6종의 수집 방식과 필드를 설명합니다.
상호작용 타입
SDK는 discord.js의 interactionCreate 이벤트를 감지하여 6가지 타입으로 분류합니다.
| 타입 | event_type | 설명 |
|---|---|---|
| 슬래시 명령어 | interaction_slash | Chat Input Command 실행 |
| 버튼 | interaction_button | 버튼 컴포넌트 클릭 |
| 셀렉트 메뉴 | interaction_select | String/User/Role/Channel/Mentionable 셀렉트 선택 |
| 모달 | interaction_modal | 모달(폼) 제출 |
| 컨텍스트 메뉴 | interaction_context_menu | 사용자/메시지 우클릭 메뉴 실행 |
| 자동완성 | interaction_autocomplete | 슬래시 명령어 자동완성 요청 |
자동완성의 특수성
자동완성(interaction_autocomplete)은 즉시 전송되며 latencyMs가 포함되지 않습니다. 사용자가 타이핑할 때마다 발생하므로 빈도가 높을 수 있습니다.
수집 필드
모든 상호작용 타입은 동일한 데이터 구조를 공유합니다.
공통 필드 (envelope)
| 필드 | 수집 여부 | 설명 |
|---|---|---|
guild_id | ✅ | 서버 ID |
user_id | ✅ | 사용자 ID |
channel_id | ✅ | 채널 ID |
data 필드
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
commandName | string | ✅ | 명령어 이름 (전체 경로) |
interactionKind | string | 상호작용 종류 (slash, button, select 등) | |
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) |
commandName 필드
commandName은 상호작용 타입에 따라 다르게 결정됩니다.
슬래시 명령어
서브커맨드가 있으면 전체 경로가 기록됩니다.
/play rock → "play rock"
/settings set key → "settings set key"
/help → "help"버튼 / 셀렉트 / 모달
customId가 기록됩니다. 이때 스노우플레이크(17~20자리 숫자)는 {id}로 정규화됩니다.
confirm_123456789012345678 → "confirm_{id}"
ticket-close-987654321098765432 → "ticket-close-{id}"
settings_modal → "settings_modal"참고
명령어 랭킹을 확인할 때는 반드시 interaction_kind = slash 필터를 사용하세요. 필터 없이 조회하면 버튼의 정규화된 customId가 명령어와 섞여 정확한 랭킹을 알 수 없습니다.
컨텍스트 메뉴
메뉴 이름이 그대로 기록됩니다.
"사용자 정보 보기"
"메시지 신고"응답 지연 측정
SDK는 상호작용의 응답 메서드(reply, deferReply, editReply, followUp)를 인스턴스 레벨로 패치하여 지연 시간을 측정합니다.
| 필드 | 의미 |
|---|---|
latencyMs | 상호작용 수신 → 최초 응답(reply 또는 deferReply) 시점 |
deferMs | 상호작용 수신 → deferReply 시점 (defer 사용 시에만) |
15초 타임아웃
Discord는 상호작용 수신 후 3초(defer 없이) 또는 15초(defer 후) 이내에 응답해야 합니다. SDK는 15초 동안 어떤 응답 메서드도 호출되지 않으면 timedOut: true를 설정합니다.
오류 발생 시
패치된 응답 메서드가 reject되거나 throw하면 command_error 이벤트가 별도로 수집됩니다. interactionId 필드로 원래 상호작용 이벤트와 연결할 수 있습니다.
// 이 오류는 command_error 이벤트로 자동 수집됩니다
await interaction.reply({ content: 'OK' }); // → 실패 시 command_error대시보드에서 확인
상호작용 데이터는 대시보드의 상호작용 카테고리에서 확인합니다.
- 총합: 전체 상호작용 건수 추이
- 명령어: 슬래시 명령어별 사용 랭킹과 추이
- 버튼 / 셀렉트 / 모달 / 컨텍스트 메뉴: 타입별 상세
- 시간대 히트맵: 시간대별 상호작용 분포
- 자동완성: 자동완성 요청 추이
탐색(Explore)에서 interaction_kind, command, guild_id 등 다양한 차원으로 자유롭게 분석할 수 있습니다.