Discord Channel Management Skill

Discord Channel Management Skill

Overview

Discord REST API를 활용하여 서버(길드)와 채널을 관리하는 스킬입니다. Bot 토큰 기반 인증으로 채널 CRUD, 권한 관리, 메시지 전송, 웹훅 작업을 지원합니다.

Purpose

• 채널 관리: 텍스트/음성/카테고리 채널 생성, 수정, 삭제
• 권한 관리: 역할 및 사용자별 채널 권한 설정
• 메시지 작업: 메시지 전송, 조회, 삭제
• 웹훅 관리: 웹훅 생성 및 메시지 전송
• 서버 정보: 길드 정보 및 채널 목록 조회

When to Use

명시적 요청:

• "Discord 채널 만들어줘"
• "디스코드 서버에 메시지 보내줘"
• "채널 권한 설정해줘"
• "Discord 웹훅으로 알림 보내줘"
• "디스코드 채널 목록 보여줘"
• "채널 삭제해줘"

자동 활성화:

• "discord", "디스코드" 키워드 언급 시
• 채널/서버/길드 관리 요청 시
• 웹훅 설정 요청 시

Prerequisites

환경 변수

# 필수 - jelly-dotenv/​.env에 설정
DISCORD_BOT_TOKEN=           # Bot Token (Developer Portal에서 발급)

# 선택
DISCORD_APPLICATION_ID=      # Application ID
DISCORD_GUILD_ID=            # 기본 서버(길드) ID
DISCORD_DEFAULT_CHANNEL_ID=  # 기본 채널 ID

Discord Bot 설정

1. Discord Developer Portal에서 애플리케이션 생성
2. Bot 섹션에서 봇 생성 및 토큰 복사
3. OAuth2 > URL Generator에서 봇 초대 링크 생성
   • Scopes: bot, applications.commands
   • Bot Permissions: Manage Channels, Send Messages, Manage Messages
4. 생성된 URL로 봇을 서버에 초대

API Reference

Base URL

https://discord.com/​api/​v10

Authentication

Authorization: Bot YOUR_BOT_TOKEN
Content-Type: application/​json

Quick Start

채널 목록 조회

# 환경 변수 로드
source skills/​jelly-dotenv/​load-env.sh

# 길드의 채널 목록 조회
curl -s -X GET \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  "https://discord.com/​api/​v10/​guilds/​$DISCORD_GUILD_ID/​channels" | jq

텍스트 채널 생성

curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "name": "new-channel",
    "type": 0,
    "topic": "채널 설명"
  }' \
  "https://discord.com/​api/​v10/​guilds/​$DISCORD_GUILD_ID/​channels" | jq

메시지 전송

curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "content": "Hello from Claude Code!"
  }' \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​messages" | jq

채널 삭제

curl -s -X DELETE \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID" | jq

Channel Types

Permissions Bitfield

주요 권한

권한 계산

// 여러 권한 조합
const permissions = VIEW_CHANNEL | SEND_MESSAGES | MANAGE_MESSAGES;
// 1024 | 2048 | 8192 = 11264

Core Features

1. 채널 CRUD

# 채널 정보 조회
curl -s -X GET \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID" | jq

# 채널 수정
curl -s -X PATCH \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "name": "updated-name",
    "topic": "새로운 설명"
  }' \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID" | jq

# 음성 채널 생성
curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "name": "Voice Room",
    "type": 2,
    "user_limit": 10
  }' \
  "https://discord.com/​api/​v10/​guilds/​$DISCORD_GUILD_ID/​channels" | jq

# 카테고리 생성
curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "name": "My Category",
    "type": 4
  }' \
  "https://discord.com/​api/​v10/​guilds/​$DISCORD_GUILD_ID/​channels" | jq

2. 권한 관리

# 역할에 채널 권한 설정
curl -s -X PUT \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "type": 0,
    "allow": "3072",
    "deny": "0"
  }' \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​permissions/​$ROLE_ID"

# type: 0 = 역할, 1 = 멤버
# allow/​deny: 권한 비트필드 문자열

3. 메시지 작업

# 메시지 목록 조회 (최근 50개)
curl -s -X GET \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​messages?limit=50" | jq

# Embed 메시지 전송
curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "embeds": [{
      "title": "알림",
      "description": "중요한 공지사항입니다.",
      "color": 5814783,
      "fields": [
        {"name": "항목 1", "value": "내용 1", "inline": true},
        {"name": "항목 2", "value": "내용 2", "inline": true}
      ]
    }]
  }' \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​messages" | jq

# 메시지 삭제
curl -s -X DELETE \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​messages/​$MESSAGE_ID"

# 메시지 일괄 삭제 (2주 이내, 2-100개)
curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "messages": ["MESSAGE_ID_1", "MESSAGE_ID_2"]
  }' \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​messages/​bulk-delete"

4. 웹훅 관리

# 웹훅 생성
curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "name": "My Webhook"
  }' \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​webhooks" | jq

# 웹훅으로 메시지 전송 (토큰 불필요)
curl -s -X POST \
  -H "Content-Type: application/​json" \
  -d '{
    "content": "Webhook message!",
    "username": "Custom Bot Name"
  }' \
  "https://discord.com/​api/​v10/​webhooks/​$WEBHOOK_ID/​$WEBHOOK_TOKEN"

5. 스레드 관리

# 메시지에서 스레드 생성
curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "name": "Discussion Thread",
    "auto_archive_duration": 1440
  }' \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​messages/​$MESSAGE_ID/​threads" | jq

# 스레드 없이 생성 (포럼/미디어 채널용)
curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "name": "New Thread",
    "type": 11,
    "auto_archive_duration": 60
  }' \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​threads" | jq

Rate Limits

Rate Limit 헤더

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1470173023.123
X-RateLimit-Reset-After: 1.456
X-RateLimit-Bucket: abc123

Error Handling

일반적인 에러 코드

에러 응답 처리

response=$(curl -s -w "\n%{http_code}" ...)
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" = "429" ]; then
  retry_after=$(echo "$body" | jq -r '.retry_after')
  sleep "$retry_after"
fi

Security Checklist

• 봇 토큰을 코드에 하드코딩하지 않기
• 환경 변수 또는 시크릿 매니저 사용
• 필요한 최소 권한만 부여
• Rate Limit 준수
• 민감한 채널에 대한 접근 제한

Reference Documentation

• references/​api-endpoints.md - API 엔드포인트 전체 목록
• references/​permissions.md - 권한 비트필드 상세
• references/​rate-limits.md - Rate Limit 가이드

External Resources

• Discord Developer Portal: https://discord.com/developers/docs
• Discord.js Guide: https://discordjs.guide/
• Permission Calculator: https://discordapi.com/permissions.html
• Discord API Types: https://discord-api-types.dev/

---

Workflow

Step 1: 환경 확인

# 환경 변수 로드
source skills/​jelly-dotenv/​load-env.sh

# 봇 연결 테스트
curl -s -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  "https://discord.com/​api/​v10/​users/​@me" | jq .username

Step 2: 작업 유형별 분기

채널 관리:

1. 길드 채널 목록 조회
2. 채널 생성/수정/삭제 실행
3. 결과 확인

메시지 전송:

1. 대상 채널 ID 확인
2. 메시지 본문 구성 (텍스트/​Embed)
3. POST 요청 실행

웹훅 작업:

1. 채널에 웹훅 생성
2. 웹훅 URL로 메시지 전송

---

Examples

예시 1: 채널 목록 조회

사용자: "디스코드 서버의 채널 목록 보여줘"

Claude:
curl -s -X GET \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  "https://discord.com/​api/​v10/​guilds/​$DISCORD_GUILD_ID/​channels" | jq

→ 채널 목록:
| 이름 | 타입 | ID |
|------|------|-----|
| general | 텍스트 | 123456789 |
| voice-chat | 음성 | 987654321 |

예시 2: 텍스트 채널 생성

사용자: "announcements라는 공지 채널 만들어줘"

Claude:
curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{"name": "announcements", "type": 0, "topic": "공지사항"}' \
  "https://discord.com/​api/​v10/​guilds/​$DISCORD_GUILD_ID/​channels"

→ 채널 "announcements" 생성 완료 (ID: 111222333)

예시 3: Embed 메시지 전송

사용자: "알림 채널에 배포 완료 메시지 보내줘"

Claude:
curl -s -X POST \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H "Content-Type: application/​json" \
  -d '{
    "embeds": [{
      "title": "배포 완료",
      "description": "v1.2.3 배포가 완료되었습니다.",
      "color": 5763719
    }]
  }' \
  "https://discord.com/​api/​v10/​channels/​$CHANNEL_ID/​messages"

→ 메시지 전송 완료

---

Best Practices

DO:

• 봇 토큰은 환경 변수로 관리
• Rate limit 준수 (429 응답 시 대기)
• 필요한 최소 권한만 봇에 부여
• 채널 작업 전 권한 확인
• 대량 삭제 시 bulk-delete API 사용

DON'T:

• 토큰을 코드에 하드코딩하지 않기
• Rate limit 무시하고 연속 요청하지 않기
• 모든 권한을 가진 봇 사용하지 않기
• 2주 이상 된 메시지에 bulk-delete 시도하지 않기
• 사용자 DM에 무분별하게 메시지 보내지 않기

---

Troubleshooting

401 Unauthorized

# 토큰 확인
echo $DISCORD_BOT_TOKEN | head -c 20
# 토큰 형식: Bot xxxxxxxxxxx

403 Forbidden

• 봇이 해당 채널/서버에 접근 권한이 있는지 확인
• 필요한 권한(Manage Channels 등)이 부여되었는지 확인

429 Rate Limited

# retry_after 값만큼 대기 후 재시도
sleep $retry_after

50001 Missing Access

• 봇이 서버에 초대되었는지 확인
• /​invite @bot 명령으로 채널에 봇 추가

---

Version: 1.0.0 Last Updated: December 2025