온보딩 체크리스트 디스코드 봇 만들기

새 멤버가 규칙을 읽었는지, 자기소개를 했는지, 질문 채널까지 갔는지를 운영자가 일일이 확인하는 순간 온보딩이 이미 무거워진 겁니다.

온보딩 체크리스트 봇의 역할은 입구 채널을 대신하는 게 아니라, 새 멤버가 해야 할 첫 행동을 한 장짜리 진행표로 보여 주는 데 있습니다.

이 글은 입구 안내를 인터랙티브 완료 흐름으로 바꾸는 자동화 글입니다.

1. 입구 설명문을 진행표로 바꾸고 싶을 때 쓴다

이 글에서는 /온보딩 명령어를 실행하면 개인용 체크리스트 임베드와 버튼이 뜨고, 사용자가 버튼을 누르며 진행 상태를 확인하는 기본 구조를 만듭니다.

완전한 데이터 저장까지는 넣지 않고, 작동 원리를 이해하기 쉬운 형태부터 갑니다.

입구 채널 구조가 먼저 필요하다면 디스코드 서버 온보딩 채널 구성 예시와 자동 환영 인사 디스코드 봇 만들기을 먼저 보고 와야 합니다.

2. 체크 대상 채널 값부터 정리

DISCORD_TOKEN=여기에_봇_토큰
GUILD_ID=테스트_서버_ID
RULES_CHANNEL_ID=규칙채널_ID
INTRO_CHANNEL_ID=자기소개채널_ID
QUESTION_CHANNEL_ID=질문채널_ID

체크리스트 문구 안에 채널 멘션을 넣으려면 채널 ID를 미리 받아 두면 수월합니다.

3. 개인 진행표를 갱신하는 코드

import os

import discord
from discord import app_commands
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")
GUILD_ID = int(os.getenv("GUILD_ID"))
RULES_CHANNEL_ID = int(os.getenv("RULES_CHANNEL_ID"))
INTRO_CHANNEL_ID = int(os.getenv("INTRO_CHANNEL_ID"))
QUESTION_CHANNEL_ID = int(os.getenv("QUESTION_CHANNEL_ID"))

intents = discord.Intents.default()
client = discord.Client(intents=intents)
tree = app_commands.CommandTree(client)
guild = discord.Object(id=GUILD_ID)
user_progress: dict[int, set[str]] = {}


def build_embed(user_id: int) -> discord.Embed:
    progress = user_progress.get(user_id, set())

    def check(key: str) -> str:
        return "완료" if key in progress else "미완료"

    description = "\n".join([
        f"1. 규칙 확인: {check('rules')}",
        f"2. 자기소개 작성: {check('intro')}",
        f"3. 질문 채널 확인: {check('question')}",
    ])

    embed = discord.Embed(title="온보딩 체크리스트", description=description, color=discord.Color.blurple())
    embed.add_field(name="규칙 채널", value=f"<#{RULES_CHANNEL_ID}>", inline=False)
    embed.add_field(name="자기소개 채널", value=f"<#{INTRO_CHANNEL_ID}>", inline=False)
    embed.add_field(name="질문 채널", value=f"<#{QUESTION_CHANNEL_ID}>", inline=False)
    return embed


class OnboardingView(discord.ui.View):
    def __init__(self, user_id: int):
        super().__init__(timeout=300)
        self.user_id = user_id

    async def toggle(self, interaction: discord.Interaction, key: str):
        if interaction.user.id != self.user_id:
            await interaction.response.send_message("본인 체크리스트만 수정할 수 있습니다.", ephemeral=True)
            return

        progress = user_progress.setdefault(self.user_id, set())
        if key in progress:
            progress.remove(key)
        else:
            progress.add(key)

        await interaction.response.edit_message(embed=build_embed(self.user_id), view=self)

    @discord.ui.button(label="규칙 확인", style=discord.ButtonStyle.secondary)
    async def rules(self, interaction: discord.Interaction, button: discord.ui.Button):
        await self.toggle(interaction, "rules")

    @discord.ui.button(label="자기소개 작성", style=discord.ButtonStyle.secondary)
    async def intro(self, interaction: discord.Interaction, button: discord.ui.Button):
        await self.toggle(interaction, "intro")

    @discord.ui.button(label="질문 채널 확인", style=discord.ButtonStyle.secondary)
    async def question(self, interaction: discord.Interaction, button: discord.ui.Button):
        await self.toggle(interaction, "question")


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


@tree.command(name="온보딩", description="개인용 온보딩 체크리스트를 엽니다.", guild=guild)
async def onboarding(interaction: discord.Interaction):
    user_progress.setdefault(interaction.user.id, set())
    await interaction.response.send_message(
        embed=build_embed(interaction.user.id),
        view=OnboardingView(interaction.user.id),
        ephemeral=True,
    )


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

client.run(TOKEN)

이 코드는 체크 상태를 메모리에만 저장합니다.
재시작하면 초기화되지만, 입구 자동화 흐름을 이해하기에는 충분합니다.

4. 버튼 갱신과 개인 제한 먼저 확인

python main.py

실행 후 `/온보딩`을 입력합니다.
체크리스트가 본인에게만 보이는 ephemeral 메시지로 뜨고, 버튼을 누를 때마다 상태가 바뀌면 정상입니다.

5. ephemeral 상태와 저장 범위에서 막히는 부분

• 버튼을 남이 눌러 버리는 경우 유저 ID 확인 분기를 안 넣은 경우가 많습니다.
• 채널 멘션이 이상하게 보이는 경우 채널 ID를 잘못 넣었을 가능성이 큽니다.
• 재시작 후 체크 상태가 사라지는 경우 지금 구조는 메모리 저장이라 정상입니다.
  
  운영 단계에서는 파일이나 DB 저장을 붙여야 합니다.

6. 체크리스트는 세 칸 안팎이 가장 읽히기 쉽다

항목을 너무 많이 넣으면 체크리스트도 안 읽힙니다.

입구에서 반드시 필요한 행동만 남겨야 합니다.

보통은 아래 정도면 충분합니다.

• 규칙 읽기
• 자기소개 작성
• 질문 채널 또는 시작 채널 확인

7. 인증 흐름과 같이 붙이면 더 자연스럽다

규칙 동의, 인증 역할, 체크리스트가 따로 놀면 유저가 무엇부터 해야 할지 헷갈립니다.

규칙 동의가 끝난 뒤 /온보딩을 안내하는 식으로 붙이면 입구 흐름이 부드럽습니다.

인증 구조를 먼저 정리하려면 규칙 동의 인증 디스코드 봇 만들기과 인증 디스코드 봇 만들기을 같이 보면 됩니다.

8. 운영 기준도 미리 정해야 한다

체크리스트가 있다고 해서 유저가 실제로 다 읽는 것은 아닙니다.

체크 항목은 확인 여부를 보여 주는 참고 장치로 보고, 진짜 입구 구조는 채널 문구와 권한에서 잡아야 합니다.

그래서 체크리스트를 만들더라도 디스코드 서버 규칙 채널 작성법과 디스코드 공지 채널 운영법을 같이 손봐야 합니다.

9. 상시 운영이라면 배포도 같이 본다

온보딩은 새 멤버가 들어올 때마다 바로 써야 하는 기능입니다.

개발용 PC에서만 돌리면 입구 자동화가 쉽게 끊깁니다.

실제 서버에서 계속 돌릴 생각이라면 24시간 디스코드 봇 무료 호스팅, 디스호스트처럼 상시 실행 환경을 같이 준비해야 합니다.

10. 체크리스트는 입구를 보조할 뿐, 입구를 대체하지는 않는다

체크리스트가 돌아가기 시작하면 다음에는 입구 문구와 채널 배치를 더 짧고 분명하게 다듬을 차례입니다.

입구 구조 자체를 더 읽히게 만들고 싶다면 디스코드 서버 온보딩 채널 구성 예시와 디스코드 서버 규칙 채널 작성법을 먼저 다듬어야 합니다.