Discord Channel Management Skill

Overview

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

Purpose

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

When to Use

명시적 요청:

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

자동 활성화:

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

Prerequisites

환경 변수

bash

# 필수 - 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 설정

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

API Reference

Base URL

https://discord.com/api/v10

Authentication

bash

Authorization: Bot YOUR_BOT_TOKEN
Content-Type: application/json

Quick Start

채널 목록 조회

bash

# 환경 변수 로드
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

텍스트 채널 생성

bash

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

메시지 전송

bash

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

채널 삭제

bash

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

Channel Types

Type	값	설명
GUILD_TEXT	0	텍스트 채널
DM	1	DM 채널
GUILD_VOICE	2	음성 채널
GROUP_DM	3	그룹 DM
GUILD_CATEGORY	4	카테고리
GUILD_ANNOUNCEMENT	5	공지 채널
ANNOUNCEMENT_THREAD	10	공지 스레드
PUBLIC_THREAD	11	공개 스레드
PRIVATE_THREAD	12	비공개 스레드
GUILD_STAGE_VOICE	13	스테이지 채널
GUILD_DIRECTORY	14	디렉토리
GUILD_FORUM	15	포럼 채널
GUILD_MEDIA	16	미디어 채널

Permissions Bitfield

주요 권한

권한	Hex	Decimal	설명
VIEW_CHANNEL	0x400	1024	채널 보기
MANAGE_CHANNELS	0x10	16	채널 관리
SEND_MESSAGES	0x800	2048	메시지 전송
MANAGE_MESSAGES	0x2000	8192	메시지 관리
MANAGE_ROLES	0x10000000	268435456	역할/권한 관리
ADMINISTRATOR	0x8	8	관리자 (모든 권한)

권한 계산

javascript

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

Core Features

1. 채널 CRUD

bash

# 채널 정보 조회
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. 권한 관리

bash

# 역할에 채널 권한 설정
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. 메시지 작업

bash

# 메시지 목록 조회 (최근 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. 웹훅 관리

bash

# 웹훅 생성
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. 스레드 관리

bash

# 메시지에서 스레드 생성
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

범위	제한
전역	50 req/sec
메시지 전송	5 msg/5sec/channel
메시지 삭제	별도 높은 제한
채널 수정	2 req/10min/channel

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

일반적인 에러 코드

코드	의미	해결 방법
401	Unauthorized	토큰 확인
403	Forbidden	봇 권한 확인
404	Not Found	ID 확인
429	Rate Limited	재시도 대기
50001	Missing Access	채널 접근 권한 없음
50013	Missing Permissions	필요 권한 부족

에러 응답 처리

bash

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: 환경 확인

bash

# 환경 변수 로드
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: 작업 유형별 분기

채널 관리:

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

메시지 전송:

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

웹훅 작업:

채널에 웹훅 생성
웹훅 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

bash

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

403 Forbidden

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

429 Rate Limited

bash

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

50001 Missing Access

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

Version: 1.0.0 Last Updated: December 2025

Search AI Tools

Install this agent skill to your Project

SKILL.md

Discord Channel Management Skill

Overview

Purpose

When to Use

Prerequisites

환경 변수

Discord Bot 설정

API Reference

Base URL

Authentication

Quick Start

채널 목록 조회

텍스트 채널 생성

메시지 전송

채널 삭제

Channel Types

Permissions Bitfield

주요 권한

권한 계산

Core Features

1. 채널 CRUD

2. 권한 관리

3. 메시지 작업

4. 웹훅 관리

5. 스레드 관리

Rate Limits

Rate Limit 헤더

Error Handling

일반적인 에러 코드

에러 응답 처리

Security Checklist

Reference Documentation

External Resources

Workflow

Step 1: 환경 확인

Step 2: 작업 유형별 분기

Examples

예시 1: 채널 목록 조회

예시 2: 텍스트 채널 생성

예시 3: Embed 메시지 전송

Best Practices

Troubleshooting

401 Unauthorized

403 Forbidden

429 Rate Limited

50001 Missing Access