디스코드 봇 특화 설정

임베드 및 컴포넌트 V2 활용

디스코드 메시지 카드(Embed) 디자인 양식과 사용자 상호작용을 돕는 버튼, 선택 메뉴, 그리고 최신 컴포넌트 V2(Components V2) 레이아웃 코드 구현법을 익힙니다.

디스코드 일반 텍스트 문장을 넘어 시각적으로 정돈된 카드 정보 창을 출력할 수 있는 임베드(Embed) 기능과 사용자가 마우스로 직접 누를 수 있는 인터랙티브 UI 요소인 컴포넌트(Components) 적용 프로토콜을 설명합니다.


1. 리치 임베드(Rich Embed) 빌딩 규칙

임베드는 제목, 설명, 썸네일 이미지, 주요 필드 목록, 하단 꼬리말(Footer) 등으로 구성되는 풍부한 포맷의 안내 카드 영역입니다.

Node.js (discord.js v14) 임베드 예제

const { EmbedBuilder } = require('discord.js');

const welcomeEmbed = new EmbedBuilder()
  .setColor(0x0071E3) // 애플 블루 브랜드 색상 코드
  .setTitle('디스호스트 서버 안내')
  .setDescription('무료 고성능 디스코드 봇 호스팅에 오신 것을 환영합니다.')
  .addFields(
    { name: '기본 메모리', value: '128MB', inline: true },
    { name: '디스크 용량', value: '512MB', inline: true }
  )
  .setTimestamp()
  .setFooter({ text: 'DisHost Docs Team' });

// 채널에 전송할 때 embeds 배열에 담아 송신합니다.
message.channel.send({ embeds: [welcomeEmbed] });

2. 인터랙티브 컴포넌트 v2 (Components v2)

디스코드는 최근 봇 인터페이스 고도화를 위해 버튼과 메뉴의 레이아웃 배열을 세밀히 제어할 수 있는 차세대 Components V2 사양을 적용하기 시작했습니다. 그리드 형태의 배치나 모달(Modal) 응답을 유연하게 다룰 수 있습니다.

Python (discord.py v2) 버튼 컴포넌트 구현

import discord

class InteractiveView(discord.ui.View):
    def __init__(self):
        super().__init__(timeout=60) # 60초 뒤 버튼 작동 비활성화

    @discord.ui.button(label="서버 정보 조회", style=discord.ButtonStyle.primary)
    async def info_button(self, interaction: discord.Interaction, button: discord.ui.Button):
        # 버튼을 누른 멤버 본인에게만 보이는 메시지로 응답합니다.
        await interaction.response.send_message(
            content="본 봇은 디스호스트 컨테이너(128MB)에서 작동 중입니다.", 
            ephemeral=True
        )

# 커맨드 함수 내에서 view 매개변수로 탑재하여 발송합니다.
@bot.command(name='메뉴')
async def menu(ctx):
    await ctx.send("원하는 작업을 선택해 주세요:", view=InteractiveView())

3. 컴포넌트 사용 가이드라인

  • Custom ID 충돌 주의: 버튼이나 드롭다운 메뉴를 만들 때 선언하는 custom_id 값은 디스코드 이벤트 핸들러가 컴포넌트를 고유 식별하는 핵심 열쇠입니다. 여러 컴포넌트에 같은 custom_id를 사용하면 이벤트 충돌 및 오작동이 유발됩니다.
  • 응답 제한 타임아웃 (3초): 사용자가 버튼을 클릭한 시점부터 봇 소스코드가 디스코드 API 서버에 연동 응답(interaction.deferReply() 또는 interaction.response.send_message())을 전달하기까지 최대 3초의 임계 한계 시간이 존재합니다. 무거운 연산이 실행되어야 할 땐 반드시 3초 내에 임시 응답 지연 처리(Defer)를 선포하여 타임아웃 오류를 차단해 주어야 합니다.