Discord 특권 게이트웨이 인텐트는 봇 소유자가 개발자 포털에서 직접 켜야 하는 세 가지 옵트인 권한(Presence, Server Members, Message Content)입니다. 이 설정을 켜지 않으면 Discord는 해당 데이터를 게이트웨이로 보내지 않습니다. 멤버 목록과 메시지 내용은 기본적으로 민감한 정보이기 때문에 이런 권한이 존재합니다. 하나라도 빠뜨리면 봇이 크게 오류를 내지 않고, 필요한 이벤트를 조용히 받지 못하게 됩니다. “봇은 온라인인데 아무것도 안 해요”라는 문제가 인텐트 토글 하나로 해결되는 경우가 많은 이유입니다.

Two privileged intents stay switched on and let data through while a third stays off and blocks it. Developer Portal Server Members Message Content Presence Bot Welcome msgs ✓ Auto-responders ✓ Live presence ✗

게이트웨이 인텐트란 무엇인가

봇이 Discord에 연결될 때, 자신이 속한 모든 서버에서 일어나는 모든 이벤트를 자동으로 받지는 않습니다. 인텐트라고 불리는 이벤트 범주를 구독합니다. 메시지 이벤트, 음성 상태 이벤트, 서버 업데이트 이벤트 등이 있습니다. 대부분의 인텐트는 코드에서 선언하기만 하면 되고, Discord가 따로 묻지 않고 허용합니다. 세 가지는 다릅니다. 이들은 서버에 누가 있는지, 멤버들이 무엇을 입력하는지와 같은 데이터가 강력해서, 코드만이 아니라 봇 소유자가 개발자 포털에서 명시적으로 옵트인하도록 요구합니다. 그래서 특권 인텐트라고 부릅니다.

봇 코드가 특권 인텐트를 요청했는데 소유자가 해당 애플리케이션에서 이를 켜지 않았다면, Discord는 로그인을 아예 거부합니다. 봇이 일부 기능만 제한된 상태로 온라인이 되는 것이 아니라, 아예 연결되지 않으며 게이트웨이는 “disallowed intents” 오류와 함께 연결을 끊습니다.

세 가지 특권 인텐트

  • Presence Intent. 모든 멤버의 온라인/자리 비움/오프라인 상태와 커스텀 활동. 실시간 접속 정보를 보여 주는 봇이 사용하며, Noxyr를 포함한 대부분의 티켓, 모더레이션, 커머스 봇은 필요하지 않습니다.
  • Server Members Intent. 전체 멤버 목록과 입장 및 퇴장 이벤트, 역할 변경, 닉네임 업데이트. 입장 메시지, 멤버 수, 안티 레이드 감지의 기반이 되는 인텐트입니다.
  • Message Content Intent. 메시지가 전송되었다는 사실이 아니라 메시지의 실제 텍스트. 이 인텐트가 없으면 봇은 누군가 채널에 글을 올렸다는 것은 알 수 있지만, 무엇을 입력했는지는 읽을 수 없습니다.

Noxyr의 코드는 세 가지 중 두 가지, 즉 Server Members Intent와 Message Content Intent를 요청합니다. Presence Intent는 Noxyr의 어떤 기능에도 포함되어 있지 않으므로 요청하지 않으며, 켤 필요도 없습니다.

Server Members Intent가 없으면 무엇이 깨지나

Server Members Intent는 봇이 GUILD_MEMBER_ADD와 GUILD_MEMBER_REMOVE 이벤트를 받을 수 있게 해 줍니다. 거의 모든 멤버 관련 기능이 의존하는 입장 및 퇴장 이벤트입니다.

  • 입장 메시지. 입장 메시지는 입장 시 작동합니다. 이 인텐트가 없으면 봇은 입장 이벤트를 받지 못하므로, 아무것도 게시되지 않고 자동 역할도 부여되지 않습니다.
  • 멤버 수. 실시간 멤버 수 채널이나 위젯은 같은 입장 및 퇴장 이벤트로 업데이트됩니다. 이 인텐트가 없으면 마지막으로 본 수에서 멈춥니다.
  • 안티 너크 및 레이드 보호. 대량 입장 레이드를 감지하거나 의심스러운 역할 및 닉네임 변경을 감시하는 것은 모두 멤버 이벤트에 의존합니다. 인텐트를 끄면 이 감지 경로 전체가 작동하지 않게 됩니다.
  • 인증 절차. 멤버의 가입 날짜, 역할, 계정 나이를 확인하는 모든 관문은 이 인텐트가 제공하는 멤버 객체가 필요합니다.

Message Content Intent가 없으면 무엇이 깨지나

Message Content Intent는 메시지의 실제 텍스트를 열어 줍니다. 이 인텐트가 없어도 봇은 채널에 메시지가 들어왔고 누가 보냈는지는 알 수 있습니다. 다만 무슨 내용인지는 읽을 수 없습니다.

  • 자동 응답기. “환불”이나 “결제는 어떻게 하나요” 같은 트리거 단어를 매칭하려면 메시지 텍스트를 읽어야 합니다. 내용이 없으면 매칭도 없고, 응답도 없습니다.
  • AI 채팅 응답. 채널이나 멘션에서 질문에 답하는 AI 어시스턴트는 질문 자체가 필요합니다. 이 인텐트가 없으면 누군가 말했다는 것은 알지만, 모델에 보낼 내용이 없습니다.
  • 티켓 대화 기록. 스태프와 멤버가 티켓에서 실제로 무엇을 말했는지 기록하는 대화 기록에는 메시지 내용이 필요합니다. 이 인텐트가 없으면 내용 없이 타임스탬프와 사용자 이름 목록만 남습니다.
  • 접두사 기반 모더레이션. 금지어, 초대 링크, 스팸 패턴을 찾아내는 기능은 자동 응답기와 같은 방식으로 메시지 내용을 읽습니다.

슬래시 명령어는 어느 경우에도 영향을 받지 않습니다. Discord가 명령어 입력을 일반 메시지와 별도로 전달하기 때문입니다. 이 인텐트에 의존하는 기능은 일반 메시지에서 멤버가 입력한 내용을 읽는 기능에 한정됩니다.

개발자 포털에서 인텐트를 켜는 방법

  1. Discord 개발자 포털을 열고 봇의 애플리케이션을 선택하세요.
  2. 왼쪽 사이드바에서 Bot을 클릭하세요.
  3. Privileged Gateway Intents 섹션까지 스크롤하세요.
  4. Server Members Intent와 Message Content Intent를 켜세요(실시간 상태 데이터가 꼭 필요한 봇에만 Presence Intent를 추가하세요).
  5. 변경 사항을 저장하고 봇을 재시작하거나 다시 연결해서, 다음 로그인 때 새 인텐트가 적용되도록 하세요.

이 토글은 다음 게이트웨이 연결부터 적용되며, 이미 로그인된 봇에는 즉시 적용되지 않습니다. 세션 도중에 인텐트를 끈 봇은 보통 Discord에 의해 연결이 끊어지고, 인텐트를 다시 켠 뒤 다시 연결해야 합니다.

서버 100개 인증 규칙

서버 100개 미만에서 운영하는 봇은 포털에서 스위치를 켜는 것만으로 충분합니다. 봇의 설치 수가 서버 100개를 넘으면, Discord는 그 규모에서 특권 인텐트를 사용하기 전에 봇 인증을 받도록 요구합니다. 인증은 소유자가 봇을 제출하여 승인받는 심사 절차입니다. 인증을 받지 않은 봇이 기준을 넘으면, 이미 들어가 있는 서버에서는 계속 실행되지만 인증이 승인되거나, 엄격히 필요하지 않은 특권 인텐트를 끌 때까지 새 서버에 참여하지 못하도록 제한됩니다.

이것은 Discord 플랫폼의 규칙이며, 개별 봇 호스트가 통제할 수 있는 것이 아닙니다. Server Members나 Message Content처럼 데이터에 민감한 인텐트가, 봇이 그 데이터를 어떻게 쓰는지에 대한 Discord 자체 검토 없이 대규모로 배포되지 않도록 하기 위한 것입니다.

Noxyr가 토큰을 받기 전에 두 인텐트를 확인하는 이유

Noxyr의 커스텀 봇 기능은 여러분이 제공한 봇 토큰으로 전체 기능 세트를 실행합니다. 입장 메시지, 멤버 수, AI 채팅, 티켓 대화 기록, 자동 응답기는 모두 위의 두 인텐트에 의존하므로, 대시보드는 Server Members Intent와 Message Content Intent가 켜져 있는지 확인한 뒤에야 토큰을 받습니다. 두 인텐트 중 하나라도 꺼져 있는 상태로 붙여넣은 토큰은 처음부터 거부됩니다. 받아들인 뒤 나중에 헷갈리는 게이트웨이 오류와 함께 조용히 실패하게 두지 않습니다.

봇이 이미 실행 중일 때 인텐트가 꺼지는 경우(예를 들어 몇 달 뒤 누군가 포털에서 체크를 해제한 경우), Discord 게이트웨이는 4013 또는 4014 코드와 함께 연결을 끊습니다. Noxyr의 호스팅 노드는 이 특정 종료 코드를 감지해 봇을 끄고, 어떤 설정을 고쳐야 하는지 쉬운 말로 상태 메시지를 보냅니다. 조용한 재연결 루프에 빠져 있게 두지 않습니다. 이 오류와 그 밖의 일반적인 오프라인 원인에 대한 자세한 설명은 게이트웨이 오류 4004/4014 문제 해결 가이드에 있습니다.

자주 묻는 질문

Noxyr 커스텀 봇에 Presence Intent가 필요한가요? 아니요. Noxyr는 Server Members Intent와 Message Content Intent만 요청합니다. Presence Intent는 꺼 둬도 됩니다.

토글을 켰는데도 봇에 “disallowed intents”가 뜨는 이유는 무엇인가요? 게이트웨이는 새로 로그인할 때에만 현재 상태를 읽습니다. 포털 설정을 저장한 뒤 봇을 재시작해서, 새 인텐트가 적용된 상태로 다시 연결되도록 하세요.

Message Content Intent를 켜면 Discord가 봇에 메시지 기록을 공유하나요? 아니요. 봇이 연결되어 있고 해당 채널에 접근할 수 있는 동안 전송된 메시지에만 영향을 줍니다. 봇이 있지 않았던 시점의 과거 메시지에 소급해서 접근 권한을 주지는 않습니다.

특권 인텐트를 요청하면 봇이 차단되나요? 아니요. 입장 메시지, 자동 응답기, AI 응답처럼 그 인텐트가 필요한 기능을 위해 요청하고 사용하는 것이 바로 그 인텐트의 목적입니다. 인증은 대규모 봇을 위한 절차이며, 처벌이 아닙니다.

전체 설정 과정은 커스텀 봇 문서에서 확인하거나, Noxyr를 무료로 추가하세요. 토큰 기반 커스텀 봇 대신 메인 봇을 쓰면 인텐트 설정을 아예 건너뛸 수 있습니다.