게이트웨이 인텐트 설정

디스코드 봇은 실시간으로 사용자 액션을 수신하기 위해 게이트웨이 웹소켓(Gateway WebSocket) 연결을 활용합니다. 이때 디스코드 API 서버에 어떤 이벤트를 선별해 구독하겠다는 청원 신호인 인텐트(Intents)를 올바르게 정의하지 않으면, 봇이 온라인 상태임에도 어떠한 메시지에도 응답하지 않는 먹통 상태가 됩니다.

1단계: 디스코드 개발자 센터 승인

기본 보안 인텐트 외에 멤버 리스트나 채팅 내용 등을 수집하려면 개발자 센터 단의 사전 토글 스위치 활성화가 의무적입니다.

1. 디스코드 개발자 센터(Discord Developer Portal)의 본인 봇 애플리케이션으로 진입합니다.
2. 왼쪽 메뉴바에서 Bot 탭으로 이동합니다.
3. Privileged Gateway Intents 섹션까지 스크롤을 내립니다.
4. 필요로 하는 스위치를 ON으로 전환합니다:
   • Presence Intent: 서버 멤버들의 온라인/자리 비움/다른 게임 가동 여부 감지.
   • Server Members Intent: 서버 멤버 가입/탈퇴 이벤트 및 닉네임 목록 갱신 감지.
   • Message Content Intent: 사용자가 보낸 채팅 내용 문자열 읽기. (채팅 감지형 봇에 필수)
5. 변경 사항 적용을 위해 Save Changes를 클릭합니다.

2단계: 소스코드 내 Intents 선언 명시

개발자 포털에서 스위치를 켰다면, 실행 프로그램 코드 생성 옵션에서도 같은 범위의 인텐트를 명확히 명시하여 세션을 연결해야 합니다.

Node.js (discord.js v14)

const { Client, GatewayIntentBits } = require('discord.js');

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,           // 서버 기본 구성 이벤트 수신
    GatewayIntentBits.GuildMessages,    // 서버 메시지 발송 감지
    GatewayIntentBits.MessageContent    // 메시지 텍스트 파싱 허용
  ]
});

Python (discord.py v2)

import discord
from discord.ext import commands

intents = discord.Intents.default()
intents.message_content = True  # 메시지 텍스트 파싱 허용
intents.members = True          # 멤버 리스트 추적 허용

bot = commands.Bot(command_prefix='!', intents=intents)

흔한 문제 및 자가 진단 FAQ

Q. 봇이 켜졌는데 명령어 입력에 전혀 대답을 안 합니다.

• 원인: Message Content Intent 스위치가 디스코드 개발자 센터에서 꺼져 있거나 코드 내 intents 배열에 GatewayIntentBits.MessageContent 누락이 발생한 상태입니다.
• 자가 진단 방법: 봇의 로그 콘솔에 on_message 혹은 messageCreate 로그 리스너를 간단히 찍어 인풋 텍스트가 null 혹은 빈 문자열로 뭉개져 도달하는지 확인합니다.