0
# Nextcord Channel System Documentation
1
2
This knowledge tile documents the comprehensive Channel system in nextcord, covering all Discord channel types and their functionality.
3
4
## Channel Types Overview
5
6
Nextcord supports all Discord channel types with dedicated classes and functionality:
7
8
```python
9
from nextcord import ChannelType
10
11
# Guild Channel Types
12
ChannelType.text = 0 # Text channels
13
ChannelType.voice = 2 # Voice channels
14
ChannelType.category = 4 # Category channels
15
ChannelType.news = 5 # News/Announcement channels
16
ChannelType.stage_voice = 13 # Stage channels
17
ChannelType.forum = 15 # Forum channels
18
19
# Thread Types
20
ChannelType.news_thread = 10 # News thread
21
ChannelType.public_thread = 11 # Public thread
22
ChannelType.private_thread = 12 # Private thread
23
24
# Private Channel Types
25
ChannelType.private = 1 # DM channels
26
ChannelType.group = 3 # Group DM channels
27
```
28
29
## Text Channels
30
31
Text channels are the primary means of text communication in Discord guilds.
32
33
### Text Channel Class { .api }
34
35
```python
36
class TextChannel(abc.Messageable, abc.GuildChannel, Hashable, PinsMixin):
37
"""Represents a Discord guild text channel.
38
39
Attributes
40
----------
41
name: str
42
The channel name.
43
guild: Guild
44
The guild the channel belongs to.
45
id: int
46
The channel ID.
47
category_id: Optional[int]
48
The category channel ID this channel belongs to, if applicable.
49
topic: Optional[str]
50
The channel's topic. None if it doesn't exist.
51
position: int
52
The position in the channel list starting at 0.
53
last_message_id: Optional[int]
54
The last message ID sent to this channel.
55
slowmode_delay: int
56
Slowmode delay in seconds. 0 means disabled.
57
flags: ChannelFlags
58
Extra features of the channel.
59
nsfw: bool
60
If the channel is marked as "not safe for work".
61
default_auto_archive_duration: int
62
Default auto archive duration in minutes for threads.
63
default_thread_slowmode_delay: int
64
Default slowmode delay for new threads in this channel.
65
"""
66
```
67
68
### Message Management { .api }
69
70
```python
71
# Send messages
72
await text_channel.send("Hello world!")
73
await text_channel.send("Hello", embed=embed, file=file)
74
75
# Fetch message history
76
async for message in text_channel.history(limit=100):
77
print(f"{message.author}: {message.content}")
78
79
# Get specific message
80
message = await text_channel.fetch_message(message_id)
81
82
# Delete messages
83
await text_channel.delete_messages([msg1, msg2, msg3])
84
85
# Purge messages with conditions
86
def is_bot_message(m):
87
return m.author.bot
88
89
deleted = await text_channel.purge(limit=50, check=is_bot_message)
90
```
91
92
### Thread Creation { .api }
93
94
```python
95
# Create thread from message
96
thread = await text_channel.create_thread(
97
name="Discussion Thread",
98
message=message, # Message to create thread from
99
auto_archive_duration=1440, # 24 hours
100
reason="Starting discussion"
101
)
102
103
# Create private thread
104
private_thread = await text_channel.create_thread(
105
name="Private Discussion",
106
type=ChannelType.private_thread,
107
invitable=False,
108
auto_archive_duration=4320 # 3 days
109
)
110
111
# Get existing threads
112
for thread in text_channel.threads:
113
print(f"Thread: {thread.name}")
114
```
115
116
### Webhook Management { .api }
117
118
```python
119
# Create webhook
120
webhook = await text_channel.create_webhook(
121
name="My Bot Webhook",
122
avatar=avatar_bytes,
123
reason="For automated posts"
124
)
125
126
# Get all webhooks
127
webhooks = await text_channel.webhooks()
128
129
# Follow news channel (for news channels only)
130
if text_channel.is_news():
131
follower_webhook = await text_channel.follow(
132
destination=target_channel,
133
reason="Following announcements"
134
)
135
```
136
137
### Channel Editing { .api }
138
139
```python
140
# Edit text channel properties
141
edited_channel = await text_channel.edit(
142
name="new-channel-name",
143
topic="Updated channel topic",
144
slowmode_delay=5, # 5 second slowmode
145
nsfw=False,
146
category=category_channel,
147
position=2,
148
default_auto_archive_duration=60,
149
reason="Updating channel settings"
150
)
151
```
152
153
## Voice Channels
154
155
Voice channels enable voice communication within Discord guilds.
156
157
### Voice Channel Class { .api }
158
159
```python
160
class VoiceChannel(VocalGuildChannel, abc.Messageable):
161
"""Represents a Discord guild voice channel.
162
163
Attributes
164
----------
165
name: str
166
The channel name.
167
guild: Guild
168
The guild the channel belongs to.
169
id: int
170
The channel ID.
171
category_id: Optional[int]
172
The category this channel belongs to.
173
position: int
174
The position in the channel list.
175
bitrate: int
176
The channel's audio bitrate in bits per second.
177
user_limit: int
178
Maximum number of members allowed. 0 means unlimited.
179
rtc_region: Optional[VoiceRegion]
180
Voice region for this channel. None means automatic.
181
video_quality_mode: VideoQualityMode
182
Camera video quality setting.
183
last_message_id: Optional[int]
184
Last message sent to this voice channel.
185
nsfw: bool
186
If the channel is marked NSFW.
187
flags: ChannelFlags
188
Extra channel features.
189
"""
190
```
191
192
### Voice Connection { .api }
193
194
```python
195
# Connect to voice channel
196
voice_client = await voice_channel.connect(
197
timeout=60.0,
198
reconnect=True,
199
cls=VoiceClient # Custom voice client class
200
)
201
202
# Get members in voice channel
203
for member in voice_channel.members:
204
print(f"{member.name} is in voice")
205
206
# Get voice states
207
voice_states = voice_channel.voice_states
208
for user_id, voice_state in voice_states.items():
209
print(f"User {user_id}: muted={voice_state.mute}")
210
```
211
212
### Voice Channel Management { .api }
213
214
```python
215
# Edit voice channel
216
edited_voice = await voice_channel.edit(
217
name="New Voice Channel",
218
bitrate=128000, # 128 kbps
219
user_limit=10,
220
rtc_region=VoiceRegion.us_west,
221
video_quality_mode=VideoQualityMode.full,
222
reason="Updating voice settings"
223
)
224
225
# Clone voice channel
226
cloned_voice = await voice_channel.clone(
227
name="Cloned Voice Channel",
228
reason="Creating backup channel"
229
)
230
231
# Create invite
232
invite = await voice_channel.create_invite(
233
max_age=3600, # 1 hour
234
max_uses=5,
235
temporary=False,
236
unique=True
237
)
238
```
239
240
## Stage Channels
241
242
Stage channels provide structured audio events with speakers and audience.
243
244
### Stage Channel Class { .api }
245
246
```python
247
class StageChannel(VocalGuildChannel, abc.Messageable):
248
"""Represents a Discord guild stage channel.
249
250
Attributes
251
----------
252
name: str
253
The channel name.
254
guild: Guild
255
The guild the channel belongs to.
256
id: int
257
The channel ID.
258
topic: Optional[str]
259
The channel's topic.
260
category_id: Optional[int]
261
The category this channel belongs to.
262
position: int
263
The position in the channel list.
264
bitrate: int
265
Audio bitrate in bits per second.
266
user_limit: int
267
Maximum number of members allowed.
268
rtc_region: Optional[VoiceRegion]
269
Voice region for the stage.
270
video_quality_mode: VideoQualityMode
271
Video quality setting.
272
flags: ChannelFlags
273
Extra channel features.
274
nsfw: bool
275
If the channel is NSFW.
276
"""
277
```
278
279
### Stage Management { .api }
280
281
```python
282
# Get stage participants by role
283
speakers = stage_channel.speakers
284
listeners = stage_channel.listeners
285
requesting = stage_channel.requesting_to_speak
286
moderators = stage_channel.moderators
287
288
# Create stage instance
289
stage_instance = await stage_channel.create_instance(
290
topic="Weekly Community Meeting",
291
privacy_level=StagePrivacyLevel.guild_only,
292
reason="Starting community event"
293
)
294
295
# Get current stage instance
296
instance = stage_channel.instance
297
if instance:
298
print(f"Stage topic: {instance.topic}")
299
300
# Fetch stage instance
301
try:
302
instance = await stage_channel.fetch_instance()
303
except NotFound:
304
print("No active stage instance")
305
```
306
307
### Stage Channel Editing { .api }
308
309
```python
310
# Edit stage channel
311
edited_stage = await stage_channel.edit(
312
name="Updated Stage",
313
topic="New stage topic", # Note: topic is set on stage channel, not instance
314
bitrate=128000,
315
user_limit=50,
316
rtc_region=VoiceRegion.europe,
317
video_quality_mode=VideoQualityMode.full,
318
reason="Updating stage settings"
319
)
320
```
321
322
## Thread Channels
323
324
Threads provide focused sub-conversations within text and news channels.
325
326
### Thread Class { .api }
327
328
```python
329
class Thread(Messageable, Hashable, PinsMixin):
330
"""Represents a Discord thread.
331
332
Attributes
333
----------
334
name: str
335
The thread name.
336
guild: Guild
337
The guild the thread belongs to.
338
id: int
339
The thread ID.
340
parent_id: int
341
The parent channel ID.
342
owner_id: int
343
The user ID that created this thread.
344
last_message_id: Optional[int]
345
Last message ID in this thread.
346
slowmode_delay: int
347
Slowmode delay in seconds.
348
message_count: int
349
Approximate message count (capped at 50).
350
member_count: int
351
Approximate member count (capped at 50).
352
me: Optional[ThreadMember]
353
Your thread membership status.
354
archived: bool
355
Whether the thread is archived.
356
locked: bool
357
Whether the thread is locked.
358
invitable: bool
359
Whether non-moderators can invite others.
360
archiver_id: Optional[int]
361
User ID who archived this thread.
362
auto_archive_duration: int
363
Auto-archive duration in minutes.
364
archive_timestamp: datetime
365
When archived status was last updated.
366
create_timestamp: Optional[datetime]
367
Thread creation time (may be None for old threads).
368
applied_tag_ids: List[int]
369
List of forum tag IDs applied to this thread.
370
"""
371
```
372
373
### Thread Management { .api }
374
375
```python
376
# Join thread
377
await thread.join()
378
379
# Leave thread
380
await thread.leave()
381
382
# Add/remove members
383
await thread.add_user(member)
384
await thread.remove_user(member)
385
386
# Get thread members
387
async for thread_member in thread.fetch_members():
388
print(f"Member: {thread_member.member.name}")
389
390
# Edit thread
391
edited_thread = await thread.edit(
392
name="Updated Thread Name",
393
archived=False,
394
locked=False,
395
invitable=True,
396
slowmode_delay=10,
397
auto_archive_duration=4320, # 3 days
398
reason="Updating thread settings"
399
)
400
401
# Delete thread
402
await thread.delete(reason="Thread no longer needed")
403
```
404
405
### Thread Archives { .api }
406
407
```python
408
# Get archived threads from parent channel
409
async for thread in parent_channel.archived_threads(
410
limit=50,
411
before=datetime.now(),
412
private=False, # Public archived threads
413
joined=False # All threads, not just joined ones
414
):
415
print(f"Archived thread: {thread.name}")
416
417
# Get private archived threads you've joined
418
async for thread in parent_channel.archived_threads(
419
private=True,
420
joined=True
421
):
422
print(f"Private thread: {thread.name}")
423
```
424
425
## Forum Channels
426
427
Forum channels organize discussions into individual posts (threads) with tagging.
428
429
### Forum Channel Class { .api }
430
431
```python
432
class ForumChannel(abc.GuildChannel, Hashable):
433
"""Represents a Discord guild forum channel.
434
435
Attributes
436
----------
437
id: int
438
The channel ID.
439
guild: Guild
440
The guild this channel belongs to.
441
name: str
442
The channel name.
443
category_id: Optional[int]
444
The category this channel belongs to.
445
topic: str
446
Channel topic shown in Guidelines section.
447
position: int
448
Position in the channel list.
449
nsfw: bool
450
If the channel is marked NSFW.
451
slowmode_delay: int
452
Slowmode delay in seconds.
453
flags: ChannelFlags
454
Channel feature flags.
455
default_auto_archive_duration: int
456
Default auto-archive duration for threads.
457
last_message_id: int
458
Last thread starter message ID.
459
default_sort_order: SortOrderType
460
Default sort order for posts.
461
default_forum_layout: ForumLayoutType
462
Default layout for displaying posts.
463
default_thread_slowmode_delay: int
464
Default slowmode for new threads.
465
default_reaction: Optional[PartialEmoji]
466
Default reaction for posts.
467
"""
468
```
469
470
### Forum Post Management { .api }
471
472
```python
473
# Create forum post (thread)
474
post_thread = await forum_channel.create_thread(
475
name="Help with nextcord setup",
476
content="I'm having trouble setting up my bot...",
477
embed=help_embed,
478
files=[log_file],
479
applied_tags=[help_tag, python_tag],
480
auto_archive_duration=10080, # 1 week
481
slowmode_delay=0,
482
reason="User requesting help"
483
)
484
485
# Get forum threads
486
for thread in forum_channel.threads:
487
print(f"Post: {thread.name}")
488
print(f"Tags: {thread.applied_tag_ids}")
489
```
490
491
### Forum Tag Management { .api }
492
493
```python
494
# Get available tags
495
for tag in forum_channel.available_tags:
496
print(f"Tag: {tag.name} (ID: {tag.id})")
497
print(f"Moderated: {tag.moderated}")
498
print(f"Emoji: {tag.emoji}")
499
500
# Get specific tag
501
help_tag = forum_channel.get_tag(tag_id)
502
503
# Create custom tag (when editing channel)
504
from nextcord import ForumTag, PartialEmoji
505
506
new_tags = [
507
ForumTag(name="Help", emoji="❓", moderated=False),
508
ForumTag(name="Announcement", emoji="📢", moderated=True),
509
ForumTag(name="Python", emoji=PartialEmoji(name="python", id=emoji_id))
510
]
511
512
await forum_channel.edit(available_tags=new_tags)
513
```
514
515
### Forum Channel Configuration { .api }
516
517
```python
518
# Edit forum channel
519
edited_forum = await forum_channel.edit(
520
name="Updated Forum",
521
topic="Updated guidelines for the forum",
522
slowmode_delay=10,
523
default_auto_archive_duration=4320,
524
default_sort_order=SortOrderType.creation_date,
525
default_forum_layout=ForumLayoutType.list_view,
526
default_thread_slowmode_delay=5,
527
default_reaction="👍",
528
available_tags=updated_tags,
529
reason="Updating forum configuration"
530
)
531
```
532
533
## DM and Group Channels
534
535
Direct message channels enable private communication between users.
536
537
### DM Channel Class { .api }
538
539
```python
540
class DMChannel(abc.Messageable, abc.PrivateChannel, Hashable, PinsMixin):
541
"""Represents a Discord direct message channel.
542
543
Attributes
544
----------
545
recipient: Optional[User]
546
The user you're DMing with.
547
me: ClientUser
548
Your user account.
549
id: int
550
The DM channel ID.
551
"""
552
553
# Send DM
554
await dm_channel.send("Hello there!")
555
556
# Get DM history
557
async for message in dm_channel.history():
558
print(f"{message.author.name}: {message.content}")
559
```
560
561
### Group Channel Class { .api }
562
563
```python
564
class GroupChannel(abc.Messageable, abc.PrivateChannel, Hashable, PinsMixin):
565
"""Represents a Discord group channel.
566
567
Attributes
568
----------
569
recipients: List[User]
570
Users participating in the group.
571
me: ClientUser
572
Your user account.
573
id: int
574
The group channel ID.
575
owner: Optional[User]
576
The group owner.
577
owner_id: int
578
The owner's user ID.
579
name: Optional[str]
580
The group name if set.
581
"""
582
583
# Group management
584
await group_channel.leave()
585
586
# Check permissions
587
permissions = group_channel.permissions_for(user)
588
if permissions.kick_members: # Only owner can kick
589
print("User can manage group")
590
```
591
592
## Category Channels
593
594
Category channels organize and group other channels together.
595
596
### Category Channel Class { .api }
597
598
```python
599
class CategoryChannel(abc.GuildChannel, Hashable):
600
"""Represents a Discord channel category.
601
602
Attributes
603
----------
604
name: str
605
The category name.
606
guild: Guild
607
The guild this category belongs to.
608
id: int
609
The category ID.
610
position: int
611
Position in the category list.
612
nsfw: bool
613
If the category is marked NSFW.
614
flags: ChannelFlags
615
Extra category features.
616
"""
617
```
618
619
### Channel Organization { .api }
620
621
```python
622
# Get channels in category
623
text_channels = category.text_channels
624
voice_channels = category.voice_channels
625
stage_channels = category.stage_channels
626
all_channels = category.channels
627
628
# Create channels in category
629
text_chan = await category.create_text_channel(
630
"new-text-channel",
631
topic="Channel created in category",
632
slowmode_delay=5
633
)
634
635
voice_chan = await category.create_voice_channel(
636
"New Voice Channel",
637
bitrate=96000,
638
user_limit=20
639
)
640
641
stage_chan = await category.create_stage_channel(
642
"Community Stage",
643
bitrate=128000
644
)
645
646
forum_chan = await category.create_forum_channel(
647
"Help Forum",
648
topic="Ask questions here"
649
)
650
```
651
652
### Category Management { .api }
653
654
```python
655
# Edit category
656
edited_category = await category.edit(
657
name="Updated Category",
658
position=1,
659
nsfw=False,
660
overwrites=permission_overwrites,
661
reason="Reorganizing channels"
662
)
663
664
# Clone category
665
cloned_category = await category.clone(
666
name="Cloned Category",
667
reason="Creating backup category"
668
)
669
```
670
671
## Channel Permissions
672
673
Channel permissions control access and actions within channels using overwrites.
674
675
### Permission Overwrites { .api }
676
677
```python
678
from nextcord import PermissionOverwrite, Permissions
679
680
# Create permission overwrite
681
overwrite = PermissionOverwrite(
682
read_messages=True, # Explicitly allow
683
send_messages=False, # Explicitly deny
684
manage_messages=None # Use default (inherit)
685
)
686
687
# Set permissions for role/member
688
await channel.set_permissions(
689
role, # Target role or member
690
overwrite=overwrite, # Permission overwrite
691
reason="Updating channel permissions"
692
)
693
694
# Set permissions with kwargs
695
await channel.set_permissions(
696
member,
697
read_messages=True,
698
send_messages=True,
699
embed_links=False,
700
reason="Custom member permissions"
701
)
702
703
# Remove permissions (set to None)
704
await channel.set_permissions(role, overwrite=None)
705
```
706
707
### Permission Queries { .api }
708
709
```python
710
# Check permissions for member/role
711
permissions = channel.permissions_for(member)
712
if permissions.read_messages:
713
print("Member can read messages")
714
715
# Get channel overwrites
716
overwrites = channel.overwrites
717
for target, overwrite in overwrites.items():
718
print(f"{target}: {overwrite}")
719
720
# Get specific overwrite
721
member_overwrite = channel.overwrites_for(member)
722
role_overwrite = channel.overwrites_for(role)
723
724
# Check if permissions are synced with category
725
if channel.permissions_synced:
726
print("Channel inherits category permissions")
727
```
728
729
## Channel Properties and Configuration
730
731
### Common Channel Operations { .api }
732
733
```python
734
# Channel information
735
print(f"Name: {channel.name}")
736
print(f"ID: {channel.id}")
737
print(f"Created: {channel.created_at}")
738
print(f"Type: {channel.type}")
739
print(f"Guild: {channel.guild}")
740
print(f"Category: {channel.category}")
741
print(f"Position: {channel.position}")
742
print(f"Jump URL: {channel.jump_url}")
743
print(f"Mention: {channel.mention}")
744
745
# Channel flags
746
flags = channel.flags
747
if flags.pinned_thread:
748
print("Thread is pinned")
749
750
# NSFW check
751
if channel.is_nsfw():
752
print("Channel is NSFW")
753
```
754
755
### Channel Movement { .api }
756
757
```python
758
# Move channel to beginning of category
759
await channel.move(
760
beginning=True,
761
category=target_category,
762
sync_permissions=True,
763
reason="Reorganizing channels"
764
)
765
766
# Move channel to end
767
await channel.move(
768
end=True,
769
reason="Moving to bottom"
770
)
771
772
# Move before/after another channel
773
await channel.move(
774
before=other_channel,
775
offset=1, # 1 position after the before channel
776
reason="Reordering channels"
777
)
778
779
await channel.move(
780
after=other_channel,
781
category=new_category,
782
reason="Moving to new category"
783
)
784
```
785
786
### Invite Management { .api }
787
788
```python
789
# Create invite
790
invite = await channel.create_invite(
791
max_age=86400, # 24 hours (0 = never expires)
792
max_uses=10, # Max uses (0 = unlimited)
793
temporary=False, # Temporary membership
794
unique=True, # Create new unique invite
795
target_type=InviteTarget.stream, # For voice channels
796
target_user=streamer, # User to showcase
797
reason="Creating event invite"
798
)
799
800
# Get existing invites
801
invites = await channel.invites()
802
for invite in invites:
803
print(f"Invite: {invite.code} - Uses: {invite.uses}/{invite.max_uses}")
804
```
805
806
### Channel Cloning { .api }
807
808
```python
809
# Clone channel with same settings
810
cloned = await channel.clone(
811
name="cloned-channel",
812
reason="Creating backup channel"
813
)
814
815
# Clone preserves:
816
# - Permission overwrites
817
# - Category membership
818
# - NSFW status
819
# - Topic (text channels)
820
# - Bitrate/user limit (voice channels)
821
```
822
823
### Channel Deletion { .api }
824
825
```python
826
# Delete channel
827
await channel.delete(reason="Channel no longer needed")
828
829
# Note: Deleted channels cannot be recovered
830
# Consider archiving threads or moving important content first
831
```
832
833
## Import Statements
834
835
To use the channel system in your nextcord bot:
836
837
```python
838
# Core imports
839
import nextcord
840
from nextcord import (
841
TextChannel, VoiceChannel, StageChannel,
842
ForumChannel, CategoryChannel, DMChannel, GroupChannel,
843
Thread, ThreadMember
844
)
845
846
# Enums and types
847
from nextcord import (
848
ChannelType, VideoQualityMode, VoiceRegion,
849
StagePrivacyLevel, SortOrderType, ForumLayoutType
850
)
851
852
# Permission system
853
from nextcord import PermissionOverwrite, Permissions
854
855
# Forum system
856
from nextcord import ForumTag, PartialEmoji
857
858
# Flags and configuration
859
from nextcord import ChannelFlags, MessageFlags
860
861
# Utilities
862
from nextcord import AllowedMentions, File, Embed
863
```
864
865
## Usage Examples
866
867
### Basic Bot Channel Operations
868
869
```python
870
import nextcord
871
from nextcord.ext import commands
872
873
bot = commands.Bot(intents=nextcord.Intents.all())
874
875
@bot.event
876
async def on_ready():
877
print(f"Bot ready! Guilds: {len(bot.guilds)}")
878
879
# Get guild and channels
880
guild = bot.guilds[0]
881
882
# Find channels by name
883
general = nextcord.utils.get(guild.text_channels, name="general")
884
voice = nextcord.utils.get(guild.voice_channels, name="General")
885
886
if general:
887
await general.send("Bot is online!")
888
889
@bot.command()
890
async def channel_info(ctx, channel: nextcord.TextChannel = None):
891
"""Get information about a channel."""
892
channel = channel or ctx.channel
893
894
embed = nextcord.Embed(title=f"#{channel.name}")
895
embed.add_field(name="ID", value=channel.id)
896
embed.add_field(name="Category", value=channel.category or "None")
897
embed.add_field(name="Created", value=channel.created_at.strftime("%Y-%m-%d"))
898
embed.add_field(name="Members", value=len(channel.members))
899
embed.add_field(name="NSFW", value=channel.nsfw)
900
embed.add_field(name="Slowmode", value=f"{channel.slowmode_delay}s")
901
902
await ctx.send(embed=embed)
903
904
@bot.command()
905
async def create_thread(ctx, *, name):
906
"""Create a thread in the current channel."""
907
if isinstance(ctx.channel, nextcord.TextChannel):
908
thread = await ctx.channel.create_thread(
909
name=name,
910
auto_archive_duration=1440,
911
reason=f"Thread created by {ctx.author}"
912
)
913
await thread.send(f"Welcome to {name}!")
914
await ctx.send(f"Created thread: {thread.mention}")
915
else:
916
await ctx.send("Can only create threads in text channels!")
917
```
918
919
This comprehensive documentation covers all aspects of nextcord's channel system, providing developers with the knowledge needed to effectively work with Discord channels in their bots and applications.