반응 역할 디스코드 봇 만들기

반응 역할은 유저가 스스로 역할을 고를 수 있게 만드는 가장 흔한 구조입니다.

게임 선택, 지역 선택, 알림 구독 역할처럼 운영에 바로 쓰기 좋습니다.

수동으로 역할을 나눠 주는 것보다 훨씬 덜 번거롭고, 유저도 즉시 반응을 볼 수 있습니다.

초반에는 이모지 하나에 역할 하나를 붙이는 단순한 구조부터 만드는 게 가장 안정적입니다.

1. 먼저 준비할 것

기본 봇 구조와 역할 설계는 이미 끝나 있어야 합니다.

역할 이름과 계층이 정리되지 않은 상태에서 반응 역할부터 만들면 나중에 엉키기 쉽습니다.

역할 구조가 아직 애매하다면 디스코드 역할 설정 완벽 가이드, 관리자 운영진 멤버 봇 역할을 처음부터 정리하는 법을 먼저 봐야 합니다.

자동 지급 구조와 함께 보고 싶다면 자동 역할 부여 디스코드 봇 만들기도 바로 이어집니다.

2. 반응 역할 메시지를 먼저 고정한다

봇이 아무 메시지에나 반응을 감지하게 두면 관리가 어려워집니다.

역할 선택 전용 메시지 하나를 정해 두고, 그 메시지에 붙는 반응만 처리해야 덜 꼬입니다.

예시 메시지는 아래 정도면 충분합니다.

원하는 역할에 반응을 눌러 주세요.
🎮 게임 알림
📢 공지 알림
💻 개발 질문

이 메시지를 올린 뒤 메시지 ID를 복사해 코드에 넣습니다.

3. 역할 메시지와 ID 먼저 넣기

DISCORD_TOKEN=여기에_봇_토큰
REACTION_MESSAGE_ID=여기에_역할선택_메시지_ID
GAME_ROLE_ID=여기에_게임역할_ID
NOTICE_ROLE_ID=여기에_공지역할_ID
DEV_ROLE_ID=여기에_개발역할_ID

메시지 ID와 역할 ID는 개발자 모드에서 복사합니다.
이모지와 역할 매핑은 코드 딕셔너리로 두면 읽기 쉽습니다.

4. 반응 추가와 제거를 같이 묶는 코드

import os

import discord
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")
REACTION_MESSAGE_ID = int(os.getenv("REACTION_MESSAGE_ID"))

ROLE_MAP = {
    "🎮": int(os.getenv("GAME_ROLE_ID")),
    "📢": int(os.getenv("NOTICE_ROLE_ID")),
    "💻": int(os.getenv("DEV_ROLE_ID")),
}

intents = discord.Intents.default()
intents.guilds = True
intents.members = True
intents.reactions = True
client = discord.Client(intents=intents)


async def update_role(payload: discord.RawReactionActionEvent, should_add: bool):
    if payload.message_id != REACTION_MESSAGE_ID:
        return

    if payload.guild_id is None or payload.user_id == client.user.id:
        return

    emoji = str(payload.emoji)
    role_id = ROLE_MAP.get(emoji)

    if role_id is None:
        return

    guild = client.get_guild(payload.guild_id)
    if guild is None:
        return

    member = guild.get_member(payload.user_id)
    role = guild.get_role(role_id)

    if member is None or role is None:
        return

    try:
        if should_add:
            await member.add_roles(role, reason="반응 역할 지급")
            print(f"역할 지급: {member} -> {role.name}")
        else:
            await member.remove_roles(role, reason="반응 역할 해제")
            print(f"역할 해제: {member} -> {role.name}")
    except discord.Forbidden:
        print("권한 부족으로 역할 변경에 실패했습니다.")


@client.event
async def on_ready():
    print(f"로그인 성공: {client.user}")


@client.event
async def on_raw_reaction_add(payload: discord.RawReactionActionEvent):
    await update_role(payload, should_add=True)


@client.event
async def on_raw_reaction_remove(payload: discord.RawReactionActionEvent):
    await update_role(payload, should_add=False)


if not TOKEN:
    raise ValueError("DISCORD_TOKEN 값이 없습니다.")

client.run(TOKEN)

`raw` 이벤트를 쓰는 이유는 메시지가 캐시에 없더라도 반응 변화를 받을 수 있기 때문입니다.
초반에는 `on_reaction_add`로 시작하기 쉽지만, 실제 운영에서는 `raw` 쪽이 덜 불안합니다.

5. 역할 선택 메시지 올리기

먼저 아무 채널에 안내 메시지를 올립니다.

그다음 아래 순서로 준비합니다.

• 메시지 ID 복사
• 사용할 역할 ID 복사
• 안내 이모지 추가
• 봇 역할 순서 확인

봇 역할이 대상 역할보다 낮으면 여기서도 똑같이 실패합니다.

이 부분은 자동 역할 글과 같습니다.

6. 반응 한 번으로 왕복 확인하기

python main.py

실행 후 역할 선택 메시지에 반응을 달아 봅니다.
반응을 누르면 역할이 붙고, 반응을 지우면 역할이 빠져야 정상입니다.

7. 초반에 가장 자주 틀리는 부분

• 반응은 달리는데 역할이 안 붙는 경우 대부분 역할 순서 문제입니다.
• 특정 이모지만 동작하지 않는 경우 코드의 이모지 문자와 실제 메시지 반응 이모지가 정확히 같은지 봅니다.
  
  커스텀 이모지는 문자열 형태가 달라서 처음에는 일반 이모지로 시작해야 합니다.
• 메시지를 다시 올렸더니 안 되는 경우 새 메시지 ID를 .env에 반영하지 않은 경우가 많습니다.

8. 초반에는 역할 수를 적게 둔다

역할 종류가 너무 많으면 선택 메시지 자체가 지저분해집니다.

처음에는 3개 안팎으로 시작하면 보기 좋고 관리도 쉽습니다.

알림 구독, 관심 분야, 지역처럼 실제로 자주 쓰는 역할만 남겨야 합니다.

9. 반응 역할은 입구보다 중간 구간에 더 잘 맞는다

서버에 막 들어온 사람에게 역할을 너무 많이 고르게 하면 피로도가 생깁니다.

기본 역할은 자동 지급하고, 선택형 역할은 적응이 끝난 뒤 고르게 두면 흐름이 좋습니다.

입구 구조는 자동 환영 인사 디스코드 봇 만들기, 기본 권한은 자동 역할 부여 디스코드 봇 만들기, 선택형 분기는 지금 글을 함께 보면 역할 흐름이 정리됩니다.

10. 역할 선택은 입구보다 적응 구간에서 빛난다

반응 역할까지 만들었다면 다음에는 규칙 동의 여부에 따라 접근 권한을 여는 인증 구조로 넘어갈 수 있습니다.

지금 단계에서 권한 오류를 먼저 점검하고 싶다면 디스코드 봇 권한 설정법, 50013과 50001을 막는 기본 구조 정리와 디스코드 역할이 지급되지 않을 때 해결법을 같이 읽어 두면 원인 구분이 빨라집니다.