/discord-list-channels

name: discord-list-channels
description: List all channels in a Discord guild/server via the Discord API. Use this skill when the user wants to see all channels, find specific channels, or audit server structure.

Discord List Channels

List all channels in a Discord guild (server) using the Discord API v10. This skill retrieves all channels including text channels, voice channels, categories, announcement channels, and stage channels.

When to Use This Skill

Use this skill when the user wants to:

• List all channels in a Discord server
• Find a specific channel by name
• Get channel IDs for use with other operations
• Audit server channel structure
• Filter channels by type (text, voice, category)
• Export channel list for documentation

Prerequisites

• `DISCORD_BOT_TOKEN` environment variable must be set
• Bot must be a member of the target server
• Bot must have "View Channels" permission (basic permission, usually granted by default)
• Valid Discord guild ID (18-19 digit snowflake ID)

Channel Types

Channels are returned with the following type values:

| Type | Value | Description | |------|-------|-------------| | GUILD_TEXT | 0 | Text channel | | GUILD_VOICE | 2 | Voice channel | | GUILD_CATEGORY | 4 | Category (organizes channels) | | GUILD_ANNOUNCEMENT | 5 | Announcement channel | | GUILD_STAGE_VOICE | 13 | Stage channel | | GUILD_FORUM | 15 | Forum channel |

Instructions

When the user requests to list Discord channels:

1. **Validate Requirements**

• Confirm `DISCORD_BOT_TOKEN` is set in environment
• Verify guild ID is provided (18-19 digit number)

2. **Make the API Request** Use the following curl command structure:

   curl -X GET "https://discord.com/api/v10/guilds/{GUILD_ID}/channels" \
     -H "Authorization: Bot ${DISCORD_BOT_TOKEN}"

Replace `{GUILD_ID}` with the actual guild ID.

3. **Process Response**

• Channels are returned as an array
• Each channel includes: id, name, type, position, parent_id, permission_overwrites
• Sort or filter as requested by user

4. **Handle Response Codes**

• 200 Success: Channels retrieved successfully
• 401 Unauthorized: Invalid bot token
• 403 Forbidden: Bot not in server or missing permissions
• 404 Not Found: Guild doesn't exist

5. **Present Results**

• Group channels by category if applicable
• Show channel names, types, and IDs
• Format output in a readable structure
• Highlight requested channels if searching

Response Structure

Each channel object contains:

{
  "id": "123456789012345678",
  "type": 0,
  "guild_id": "987654321098765432",
  "position": 0,
  "permission_overwrites": [],
  "name": "general",
  "topic": "General discussion",
  "nsfw": false,
  "last_message_id": "111222333444555666",
  "parent_id": null
}

Additional fields for voice channels:

{
  "bitrate": 64000,
  "user_limit": 0,
  "rtc_region": null
}

Filtering Channels

By Type

Filter channels to show only specific types:

# Get all channels then filter by type
curl -s "https://discord.com/api/v10/guilds/{GUILD_ID}/channels" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | \
  jq '.[] | select(.type == 0)'  # Text channels only

Type filters:

• `.type == 0` - Text channels
• `.type == 2` - Voice channels
• `.type == 4` - Categories
• `.type == 5` - Announcement channels
• `.type == 13` - Stage channels

By Name

Search for channels by name:

# Get channels and search by name
curl -s "https://discord.com/api/v10/guilds/{GUILD_ID}/channels" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | \
  jq '.[] | select(.name | contains("general"))'

By Category

List channels in a specific category:

# Get channels in category with parent_id
curl -s "https://discord.com/api/v10/guilds/{GUILD_ID}/channels" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | \
  jq '.[] | select(.parent_id == "category_id_here")'

Organizing Output

Group by Category

Organize channels by their parent category:

# List all channels grouped by category
CHANNELS=$(curl -s "https://discord.com/api/v10/guilds/{GUILD_ID}/channels" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}")

# Get categories
echo "$CHANNELS" | jq -r '.[] | select(.type == 4) | .name + " (ID: " + .id + ")"'

# Get channels in each category
for CATEGORY_ID in $(echo "$CHANNELS" | jq -r '.[] | select(.type == 4) | .id'); do
  echo "Channels in category $CATEGORY_ID:"
  echo "$CHANNELS" | jq -r ".[] | select(.parent_id == \"$CATEGORY_ID\") | \"  - \" + .name"
done

Sort by Position

Channels have a `position` field for sorting:

curl -s "https://discord.com/api/v10/guilds/{GUILD_ID}/channels" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | \
  jq 'sort_by(.position)'

Output Formats

Simple List

Channels in server 123456789012345678:
- general (text)
- announcements (announcement)
- voice-chat (voice)
- Community (category)

Detailed List

=== Text Channels ===
general (ID: 111222333444555666)
  Topic: General discussion
  NSFW: No

announcements (ID: 111222333444555667)
  Topic: Server updates
  NSFW: No

=== Voice Channels ===
voice-chat (ID: 111222333444555668)
  User Limit: None
  Bitrate: 64kbps

=== Categories ===
Community (ID: 111222333444555669)

Hierarchical List

📁 Community (Category)
  💬 general-chat (Text)
  💬 help (Text)
  🔊 Voice Room 1 (Voice)

📁 Administration (Category)
  💬 mod-chat (Text)
  💬 admin-only (Text)

💬 welcome (Text) - No category
📢 announcements (Announcement) - No category

CSV Export

Channel ID,Name,Type,Category,Topic
111222333444555666,general,text,Community,General discussion
111222333444555667,voice-chat,voice,Community,
111222333444555668,announcements,announcement,,Server updates

Channel Type Labels

When displaying channels, use these labels:

| Type Value | Display Label | Emoji | |------------|---------------|-------|