Nextcord Channel System Documentation

from nextcord import ChannelType

# Guild Channel Types
ChannelType.text = 0          # Text channels
ChannelType.voice = 2         # Voice channels  
ChannelType.category = 4      # Category channels
ChannelType.news = 5          # News/Announcement channels
ChannelType.stage_voice = 13  # Stage channels
ChannelType.forum = 15        # Forum channels

# Thread Types
ChannelType.news_thread = 10     # News thread
ChannelType.public_thread = 11   # Public thread
ChannelType.private_thread = 12  # Private thread

# Private Channel Types
ChannelType.private = 1       # DM channels
ChannelType.group = 3         # Group DM channels

class TextChannel(abc.Messageable, abc.GuildChannel, Hashable, PinsMixin):
    """Represents a Discord guild text channel.
    
    Attributes
    ----------
    name: str
        The channel name.
    guild: Guild
        The guild the channel belongs to.
    id: int
        The channel ID.
    category_id: Optional[int]
        The category channel ID this channel belongs to, if applicable.
    topic: Optional[str]
        The channel's topic. None if it doesn't exist.
    position: int
        The position in the channel list starting at 0.
    last_message_id: Optional[int]
        The last message ID sent to this channel.
    slowmode_delay: int
        Slowmode delay in seconds. 0 means disabled.
    flags: ChannelFlags
        Extra features of the channel.
    nsfw: bool
        If the channel is marked as "not safe for work".
    default_auto_archive_duration: int
        Default auto archive duration in minutes for threads.
    default_thread_slowmode_delay: int
        Default slowmode delay for new threads in this channel.
    """

# Send messages
await text_channel.send("Hello world!")
await text_channel.send("Hello", embed=embed, file=file)

# Fetch message history
async for message in text_channel.history(limit=100):
    print(f"{message.author}: {message.content}")

# Get specific message
message = await text_channel.fetch_message(message_id)

# Delete messages
await text_channel.delete_messages([msg1, msg2, msg3])

# Purge messages with conditions
def is_bot_message(m):
    return m.author.bot

deleted = await text_channel.purge(limit=50, check=is_bot_message)

# Create thread from message
thread = await text_channel.create_thread(
    name="Discussion Thread",
    message=message,  # Message to create thread from
    auto_archive_duration=1440,  # 24 hours
    reason="Starting discussion"
)

# Create private thread
private_thread = await text_channel.create_thread(
    name="Private Discussion", 
    type=ChannelType.private_thread,
    invitable=False,
    auto_archive_duration=4320  # 3 days
)

# Get existing threads
for thread in text_channel.threads:
    print(f"Thread: {thread.name}")

# Create webhook
webhook = await text_channel.create_webhook(
    name="My Bot Webhook",
    avatar=avatar_bytes,
    reason="For automated posts"
)

# Get all webhooks
webhooks = await text_channel.webhooks()

# Follow news channel (for news channels only)
if text_channel.is_news():
    follower_webhook = await text_channel.follow(
        destination=target_channel,
        reason="Following announcements"
    )

# Edit text channel properties
edited_channel = await text_channel.edit(
    name="new-channel-name",
    topic="Updated channel topic",
    slowmode_delay=5,  # 5 second slowmode
    nsfw=False,
    category=category_channel,
    position=2,
    default_auto_archive_duration=60,
    reason="Updating channel settings"
)

class VoiceChannel(VocalGuildChannel, abc.Messageable):
    """Represents a Discord guild voice channel.
    
    Attributes
    ----------
    name: str
        The channel name.
    guild: Guild
        The guild the channel belongs to.
    id: int
        The channel ID.
    category_id: Optional[int]
        The category this channel belongs to.
    position: int
        The position in the channel list.
    bitrate: int
        The channel's audio bitrate in bits per second.
    user_limit: int
        Maximum number of members allowed. 0 means unlimited.
    rtc_region: Optional[VoiceRegion]
        Voice region for this channel. None means automatic.
    video_quality_mode: VideoQualityMode
        Camera video quality setting.
    last_message_id: Optional[int]
        Last message sent to this voice channel.
    nsfw: bool
        If the channel is marked NSFW.
    flags: ChannelFlags
        Extra channel features.
    """

# Connect to voice channel
voice_client = await voice_channel.connect(
    timeout=60.0,
    reconnect=True,
    cls=VoiceClient  # Custom voice client class
)

# Get members in voice channel
for member in voice_channel.members:
    print(f"{member.name} is in voice")

# Get voice states
voice_states = voice_channel.voice_states
for user_id, voice_state in voice_states.items():
    print(f"User {user_id}: muted={voice_state.mute}")

# Edit voice channel
edited_voice = await voice_channel.edit(
    name="New Voice Channel",
    bitrate=128000,  # 128 kbps
    user_limit=10,
    rtc_region=VoiceRegion.us_west,
    video_quality_mode=VideoQualityMode.full,
    reason="Updating voice settings"
)

# Clone voice channel
cloned_voice = await voice_channel.clone(
    name="Cloned Voice Channel",
    reason="Creating backup channel"
)

# Create invite
invite = await voice_channel.create_invite(
    max_age=3600,  # 1 hour
    max_uses=5,
    temporary=False,
    unique=True
)

class StageChannel(VocalGuildChannel, abc.Messageable):
    """Represents a Discord guild stage channel.
    
    Attributes
    ----------
    name: str
        The channel name.
    guild: Guild
        The guild the channel belongs to.
    id: int
        The channel ID.
    topic: Optional[str]
        The channel's topic.
    category_id: Optional[int]
        The category this channel belongs to.
    position: int
        The position in the channel list.
    bitrate: int
        Audio bitrate in bits per second.
    user_limit: int
        Maximum number of members allowed.
    rtc_region: Optional[VoiceRegion]
        Voice region for the stage.
    video_quality_mode: VideoQualityMode
        Video quality setting.
    flags: ChannelFlags
        Extra channel features.
    nsfw: bool
        If the channel is NSFW.
    """

# Get stage participants by role
speakers = stage_channel.speakers
listeners = stage_channel.listeners
requesting = stage_channel.requesting_to_speak
moderators = stage_channel.moderators

# Create stage instance
stage_instance = await stage_channel.create_instance(
    topic="Weekly Community Meeting",
    privacy_level=StagePrivacyLevel.guild_only,
    reason="Starting community event"
)

# Get current stage instance
instance = stage_channel.instance
if instance:
    print(f"Stage topic: {instance.topic}")

# Fetch stage instance
try:
    instance = await stage_channel.fetch_instance()
except NotFound:
    print("No active stage instance")

# Edit stage channel
edited_stage = await stage_channel.edit(
    name="Updated Stage",
    topic="New stage topic",  # Note: topic is set on stage channel, not instance
    bitrate=128000,
    user_limit=50,
    rtc_region=VoiceRegion.europe,
    video_quality_mode=VideoQualityMode.full,
    reason="Updating stage settings"
)

class Thread(Messageable, Hashable, PinsMixin):
    """Represents a Discord thread.
    
    Attributes
    ----------
    name: str
        The thread name.
    guild: Guild
        The guild the thread belongs to.
    id: int
        The thread ID.
    parent_id: int
        The parent channel ID.
    owner_id: int
        The user ID that created this thread.
    last_message_id: Optional[int]
        Last message ID in this thread.
    slowmode_delay: int
        Slowmode delay in seconds.
    message_count: int
        Approximate message count (capped at 50).
    member_count: int
        Approximate member count (capped at 50).
    me: Optional[ThreadMember]
        Your thread membership status.
    archived: bool
        Whether the thread is archived.
    locked: bool
        Whether the thread is locked.
    invitable: bool
        Whether non-moderators can invite others.
    archiver_id: Optional[int]
        User ID who archived this thread.
    auto_archive_duration: int
        Auto-archive duration in minutes.
    archive_timestamp: datetime
        When archived status was last updated.
    create_timestamp: Optional[datetime]
        Thread creation time (may be None for old threads).
    applied_tag_ids: List[int]
        List of forum tag IDs applied to this thread.
    """

# Join thread
await thread.join()

# Leave thread  
await thread.leave()

# Add/remove members
await thread.add_user(member)
await thread.remove_user(member)

# Get thread members
async for thread_member in thread.fetch_members():
    print(f"Member: {thread_member.member.name}")

# Edit thread
edited_thread = await thread.edit(
    name="Updated Thread Name",
    archived=False,
    locked=False,
    invitable=True,
    slowmode_delay=10,
    auto_archive_duration=4320,  # 3 days
    reason="Updating thread settings"
)

# Delete thread
await thread.delete(reason="Thread no longer needed")

# Get archived threads from parent channel
async for thread in parent_channel.archived_threads(
    limit=50,
    before=datetime.now(),
    private=False,  # Public archived threads
    joined=False    # All threads, not just joined ones
):
    print(f"Archived thread: {thread.name}")

# Get private archived threads you've joined
async for thread in parent_channel.archived_threads(
    private=True,
    joined=True
):
    print(f"Private thread: {thread.name}")

class ForumChannel(abc.GuildChannel, Hashable):
    """Represents a Discord guild forum channel.
    
    Attributes
    ----------
    id: int
        The channel ID.
    guild: Guild
        The guild this channel belongs to.
    name: str
        The channel name.
    category_id: Optional[int]
        The category this channel belongs to.
    topic: str
        Channel topic shown in Guidelines section.
    position: int
        Position in the channel list.
    nsfw: bool
        If the channel is marked NSFW.
    slowmode_delay: int
        Slowmode delay in seconds.
    flags: ChannelFlags
        Channel feature flags.
    default_auto_archive_duration: int
        Default auto-archive duration for threads.
    last_message_id: int
        Last thread starter message ID.
    default_sort_order: SortOrderType
        Default sort order for posts.
    default_forum_layout: ForumLayoutType
        Default layout for displaying posts.
    default_thread_slowmode_delay: int
        Default slowmode for new threads.
    default_reaction: Optional[PartialEmoji]
        Default reaction for posts.
    """

# Create forum post (thread)
post_thread = await forum_channel.create_thread(
    name="Help with nextcord setup",
    content="I'm having trouble setting up my bot...",
    embed=help_embed,
    files=[log_file],
    applied_tags=[help_tag, python_tag],
    auto_archive_duration=10080,  # 1 week
    slowmode_delay=0,
    reason="User requesting help"
)

# Get forum threads  
for thread in forum_channel.threads:
    print(f"Post: {thread.name}")
    print(f"Tags: {thread.applied_tag_ids}")

# Get available tags
for tag in forum_channel.available_tags:
    print(f"Tag: {tag.name} (ID: {tag.id})")
    print(f"Moderated: {tag.moderated}")
    print(f"Emoji: {tag.emoji}")

# Get specific tag
help_tag = forum_channel.get_tag(tag_id)

# Create custom tag (when editing channel)
from nextcord import ForumTag, PartialEmoji

new_tags = [
    ForumTag(name="Help", emoji="❓", moderated=False),
    ForumTag(name="Announcement", emoji="📢", moderated=True),
    ForumTag(name="Python", emoji=PartialEmoji(name="python", id=emoji_id))
]

await forum_channel.edit(available_tags=new_tags)

# Edit forum channel
edited_forum = await forum_channel.edit(
    name="Updated Forum",
    topic="Updated guidelines for the forum",
    slowmode_delay=10,
    default_auto_archive_duration=4320,
    default_sort_order=SortOrderType.creation_date,
    default_forum_layout=ForumLayoutType.list_view,
    default_thread_slowmode_delay=5,
    default_reaction="👍",
    available_tags=updated_tags,
    reason="Updating forum configuration"
)

class DMChannel(abc.Messageable, abc.PrivateChannel, Hashable, PinsMixin):
    """Represents a Discord direct message channel.
    
    Attributes
    ----------
    recipient: Optional[User]
        The user you're DMing with.
    me: ClientUser
        Your user account.
    id: int
        The DM channel ID.
    """

# Send DM
await dm_channel.send("Hello there!")

# Get DM history
async for message in dm_channel.history():
    print(f"{message.author.name}: {message.content}")

class GroupChannel(abc.Messageable, abc.PrivateChannel, Hashable, PinsMixin):
    """Represents a Discord group channel.
    
    Attributes
    ----------
    recipients: List[User]
        Users participating in the group.
    me: ClientUser
        Your user account.
    id: int
        The group channel ID.
    owner: Optional[User]
        The group owner.
    owner_id: int
        The owner's user ID.
    name: Optional[str]
        The group name if set.
    """

# Group management
await group_channel.leave()

# Check permissions
permissions = group_channel.permissions_for(user)
if permissions.kick_members:  # Only owner can kick
    print("User can manage group")

class CategoryChannel(abc.GuildChannel, Hashable):
    """Represents a Discord channel category.
    
    Attributes
    ----------
    name: str
        The category name.
    guild: Guild
        The guild this category belongs to.
    id: int
        The category ID.
    position: int
        Position in the category list.
    nsfw: bool
        If the category is marked NSFW.
    flags: ChannelFlags
        Extra category features.
    """

# Get channels in category
text_channels = category.text_channels
voice_channels = category.voice_channels  
stage_channels = category.stage_channels
all_channels = category.channels

# Create channels in category
text_chan = await category.create_text_channel(
    "new-text-channel",
    topic="Channel created in category",
    slowmode_delay=5
)

voice_chan = await category.create_voice_channel(
    "New Voice Channel",
    bitrate=96000,
    user_limit=20
)

stage_chan = await category.create_stage_channel(
    "Community Stage",
    bitrate=128000
)

forum_chan = await category.create_forum_channel(
    "Help Forum",
    topic="Ask questions here"
)

# Edit category
edited_category = await category.edit(
    name="Updated Category",
    position=1,
    nsfw=False,
    overwrites=permission_overwrites,
    reason="Reorganizing channels"
)

# Clone category
cloned_category = await category.clone(
    name="Cloned Category",
    reason="Creating backup category"
)

from nextcord import PermissionOverwrite, Permissions

# Create permission overwrite
overwrite = PermissionOverwrite(
    read_messages=True,      # Explicitly allow
    send_messages=False,     # Explicitly deny
    manage_messages=None     # Use default (inherit)
)

# Set permissions for role/member
await channel.set_permissions(
    role,                    # Target role or member
    overwrite=overwrite,     # Permission overwrite
    reason="Updating channel permissions"
)

# Set permissions with kwargs
await channel.set_permissions(
    member,
    read_messages=True,
    send_messages=True,
    embed_links=False,
    reason="Custom member permissions"
)

# Remove permissions (set to None)
await channel.set_permissions(role, overwrite=None)

# Check permissions for member/role
permissions = channel.permissions_for(member)
if permissions.read_messages:
    print("Member can read messages")

# Get channel overwrites
overwrites = channel.overwrites
for target, overwrite in overwrites.items():
    print(f"{target}: {overwrite}")

# Get specific overwrite
member_overwrite = channel.overwrites_for(member)
role_overwrite = channel.overwrites_for(role)

# Check if permissions are synced with category
if channel.permissions_synced:
    print("Channel inherits category permissions")

# Channel information
print(f"Name: {channel.name}")
print(f"ID: {channel.id}")
print(f"Created: {channel.created_at}")
print(f"Type: {channel.type}")
print(f"Guild: {channel.guild}")
print(f"Category: {channel.category}")
print(f"Position: {channel.position}")
print(f"Jump URL: {channel.jump_url}")
print(f"Mention: {channel.mention}")

# Channel flags
flags = channel.flags
if flags.pinned_thread:
    print("Thread is pinned")

# NSFW check
if channel.is_nsfw():
    print("Channel is NSFW")

# Move channel to beginning of category
await channel.move(
    beginning=True,
    category=target_category,
    sync_permissions=True,
    reason="Reorganizing channels"
)

# Move channel to end
await channel.move(
    end=True,
    reason="Moving to bottom"
)

# Move before/after another channel  
await channel.move(
    before=other_channel,
    offset=1,  # 1 position after the before channel
    reason="Reordering channels"
)

await channel.move(
    after=other_channel,
    category=new_category,
    reason="Moving to new category"
)

# Create invite
invite = await channel.create_invite(
    max_age=86400,           # 24 hours (0 = never expires)
    max_uses=10,             # Max uses (0 = unlimited)
    temporary=False,         # Temporary membership
    unique=True,             # Create new unique invite
    target_type=InviteTarget.stream,  # For voice channels
    target_user=streamer,    # User to showcase
    reason="Creating event invite"
)

# Get existing invites
invites = await channel.invites()
for invite in invites:
    print(f"Invite: {invite.code} - Uses: {invite.uses}/{invite.max_uses}")

# Clone channel with same settings
cloned = await channel.clone(
    name="cloned-channel",
    reason="Creating backup channel"
)

# Clone preserves:
# - Permission overwrites
# - Category membership  
# - NSFW status
# - Topic (text channels)
# - Bitrate/user limit (voice channels)

# Delete channel
await channel.delete(reason="Channel no longer needed")

# Note: Deleted channels cannot be recovered
# Consider archiving threads or moving important content first

# Core imports
import nextcord
from nextcord import (
    TextChannel, VoiceChannel, StageChannel, 
    ForumChannel, CategoryChannel, DMChannel, GroupChannel,
    Thread, ThreadMember
)

# Enums and types
from nextcord import (
    ChannelType, VideoQualityMode, VoiceRegion,
    StagePrivacyLevel, SortOrderType, ForumLayoutType
)

# Permission system
from nextcord import PermissionOverwrite, Permissions

# Forum system
from nextcord import ForumTag, PartialEmoji

# Flags and configuration  
from nextcord import ChannelFlags, MessageFlags

# Utilities
from nextcord import AllowedMentions, File, Embed

import nextcord
from nextcord.ext import commands

bot = commands.Bot(intents=nextcord.Intents.all())

@bot.event
async def on_ready():
    print(f"Bot ready! Guilds: {len(bot.guilds)}")
    
    # Get guild and channels
    guild = bot.guilds[0]
    
    # Find channels by name
    general = nextcord.utils.get(guild.text_channels, name="general")
    voice = nextcord.utils.get(guild.voice_channels, name="General")
    
    if general:
        await general.send("Bot is online!")

@bot.command()
async def channel_info(ctx, channel: nextcord.TextChannel = None):
    """Get information about a channel."""
    channel = channel or ctx.channel
    
    embed = nextcord.Embed(title=f"#{channel.name}")
    embed.add_field(name="ID", value=channel.id)
    embed.add_field(name="Category", value=channel.category or "None")
    embed.add_field(name="Created", value=channel.created_at.strftime("%Y-%m-%d"))
    embed.add_field(name="Members", value=len(channel.members))
    embed.add_field(name="NSFW", value=channel.nsfw)
    embed.add_field(name="Slowmode", value=f"{channel.slowmode_delay}s")
    
    await ctx.send(embed=embed)

@bot.command()
async def create_thread(ctx, *, name):
    """Create a thread in the current channel."""
    if isinstance(ctx.channel, nextcord.TextChannel):
        thread = await ctx.channel.create_thread(
            name=name,
            auto_archive_duration=1440,
            reason=f"Thread created by {ctx.author}"
        )
        await thread.send(f"Welcome to {name}!")
        await ctx.send(f"Created thread: {thread.mention}")
    else:
        await ctx.send("Can only create threads in text channels!")