0
# Guild Management
1
2
Comprehensive guild (server) management including member management, role management, channel organization, permissions, guild-specific features like scheduled events, moderation, and administrative functionality for Discord servers.
3
4
## Capabilities
5
6
### Guild Objects
7
8
Core guild representation with complete server information, member collections, and administrative capabilities.
9
10
```python { .api }
11
class Guild:
12
def __init__(self): ...
13
14
id: int
15
name: str
16
icon: Optional[Asset]
17
icon_hash: Optional[str]
18
splash: Optional[Asset]
19
discovery_splash: Optional[Asset]
20
banner: Optional[Asset]
21
description: Optional[str]
22
owner_id: int
23
verification_level: VerificationLevel
24
default_notifications: NotificationLevel
25
explicit_content_filter: ContentFilter
26
features: List[str]
27
mfa_level: int
28
application_id: Optional[int]
29
system_channel_id: Optional[int]
30
system_channel_flags: SystemChannelFlags
31
rules_channel_id: Optional[int]
32
max_presences: Optional[int]
33
max_members: Optional[int]
34
vanity_url_code: Optional[str]
35
premium_tier: int
36
premium_subscription_count: Optional[int]
37
preferred_locale: str
38
public_updates_channel_id: Optional[int]
39
max_video_channel_users: Optional[int]
40
max_stage_video_channel_users: Optional[int]
41
approximate_member_count: Optional[int]
42
approximate_presence_count: Optional[int]
43
nsfw_level: NSFWLevel
44
premium_progress_bar_enabled: bool
45
46
@property
47
def owner(self) -> Optional[Member]:
48
"""Guild owner member object."""
49
50
@property
51
def members(self) -> List[Member]:
52
"""All members in the guild."""
53
54
@property
55
def channels(self) -> List[GuildChannel]:
56
"""All channels in the guild."""
57
58
@property
59
def roles(self) -> List[Role]:
60
"""All roles in the guild."""
61
62
@property
63
def emojis(self) -> List[Emoji]:
64
"""All custom emojis in the guild."""
65
66
@property
67
def stickers(self) -> List[GuildSticker]:
68
"""All custom stickers in the guild."""
69
70
@property
71
def voice_channels(self) -> List[VoiceChannel]:
72
"""All voice channels in the guild."""
73
74
@property
75
def stage_channels(self) -> List[StageChannel]:
76
"""All stage channels in the guild."""
77
78
@property
79
def category_channels(self) -> List[CategoryChannel]:
80
"""All category channels in the guild."""
81
82
@property
83
def text_channels(self) -> List[TextChannel]:
84
"""All text channels in the guild."""
85
86
@property
87
def news_channels(self) -> List[NewsChannel]:
88
"""All news channels in the guild."""
89
90
@property
91
def forum_channels(self) -> List[ForumChannel]:
92
"""All forum channels in the guild."""
93
94
async def fetch_member(self, user_id: int) -> Member:
95
"""
96
Fetch a specific member by user ID.
97
98
Parameters:
99
- user_id: Discord user ID
100
101
Returns:
102
Member object
103
"""
104
105
def get_member(self, user_id: int) -> Optional[Member]:
106
"""
107
Get a member from cache by user ID.
108
109
Parameters:
110
- user_id: Discord user ID
111
112
Returns:
113
Member object if cached
114
"""
115
116
async def fetch_members(
117
self,
118
*,
119
limit: int = 1000,
120
after: Optional[Union[Snowflake, datetime]] = None
121
) -> AsyncIterator[Member]:
122
"""
123
Fetch guild members with pagination.
124
125
Parameters:
126
- limit: Maximum members to fetch
127
- after: Fetch members after this user/time
128
129
Yields:
130
Member objects
131
"""
132
133
def get_channel(self, channel_id: int) -> Optional[GuildChannel]:
134
"""
135
Get a channel from cache by ID.
136
137
Parameters:
138
- channel_id: Discord channel ID
139
140
Returns:
141
Channel object if cached
142
"""
143
144
def get_role(self, role_id: int) -> Optional[Role]:
145
"""
146
Get a role by ID.
147
148
Parameters:
149
- role_id: Discord role ID
150
151
Returns:
152
Role object if found
153
"""
154
155
async def ban(
156
self,
157
user: Union[Snowflake, User],
158
*,
159
reason: Optional[str] = None,
160
delete_message_days: int = 1,
161
delete_message_seconds: Optional[int] = None
162
) -> None:
163
"""
164
Ban a user from the guild.
165
166
Parameters:
167
- user: User to ban
168
- reason: Reason for the ban
169
- delete_message_days: Days of messages to delete (0-7, deprecated)
170
- delete_message_seconds: Seconds of messages to delete (0-604800)
171
"""
172
173
async def unban(self, user: Snowflake, *, reason: Optional[str] = None) -> None:
174
"""
175
Unban a user from the guild.
176
177
Parameters:
178
- user: User to unban
179
- reason: Reason for the unban
180
"""
181
182
async def kick(self, user: Snowflake, *, reason: Optional[str] = None) -> None:
183
"""
184
Kick a user from the guild.
185
186
Parameters:
187
- user: User to kick
188
- reason: Reason for the kick
189
"""
190
191
async def edit(
192
self,
193
*,
194
name: str = ...,
195
description: Optional[str] = ...,
196
icon: Optional[bytes] = ...,
197
banner: Optional[bytes] = ...,
198
splash: Optional[bytes] = ...,
199
discovery_splash: Optional[bytes] = ...,
200
community: bool = ...,
201
afk_channel: Optional[VoiceChannel] = ...,
202
afk_timeout: int = ...,
203
owner: Member = ...,
204
verification_level: VerificationLevel = ...,
205
default_notifications: NotificationLevel = ...,
206
explicit_content_filter: ContentFilter = ...,
207
vanity_code: str = ...,
208
system_channel: Optional[TextChannel] = ...,
209
system_channel_flags: SystemChannelFlags = ...,
210
preferred_locale: str = ...,
211
rules_channel: Optional[TextChannel] = ...,
212
public_updates_channel: Optional[TextChannel] = ...,
213
premium_progress_bar_enabled: bool = ...,
214
discoverable: bool = ...,
215
invites_disabled: bool = ...,
216
dms_disabled: bool = ...,
217
reason: Optional[str] = None
218
) -> Guild:
219
"""
220
Edit guild properties.
221
222
Parameters:
223
- name: Guild name
224
- description: Guild description
225
- icon: Guild icon bytes
226
- banner: Guild banner bytes
227
- splash: Guild invite splash bytes
228
- discovery_splash: Guild discovery splash bytes
229
- community: Enable community features
230
- afk_channel: AFK voice channel
231
- afk_timeout: AFK timeout in seconds
232
- owner: Transfer ownership
233
- verification_level: Member verification level
234
- default_notifications: Default notification settings
235
- explicit_content_filter: Content filter level
236
- vanity_code: Custom invite code
237
- system_channel: System messages channel
238
- system_channel_flags: System channel settings
239
- preferred_locale: Guild language
240
- rules_channel: Rules channel
241
- public_updates_channel: Community updates channel
242
- premium_progress_bar_enabled: Show boost progress bar
243
- discoverable: Allow discovery
244
- invites_disabled: Disable invite creation
245
- dms_disabled: Disable DMs from members
246
- reason: Audit log reason
247
248
Returns:
249
Updated guild object
250
"""
251
252
async def leave(self) -> None:
253
"""Leave the guild."""
254
255
async def delete(self) -> None:
256
"""Delete the guild (owner only)."""
257
```
258
259
### Channel Management
260
261
Guild channel creation, modification, and organization capabilities.
262
263
```python { .api }
264
class Guild:
265
async def create_text_channel(
266
self,
267
name: str,
268
*,
269
reason: Optional[str] = None,
270
category: Optional[CategoryChannel] = None,
271
position: int = ...,
272
topic: Optional[str] = None,
273
slowmode_delay: int = 0,
274
nsfw: bool = False,
275
news: bool = False,
276
overwrites: Optional[Dict[Union[Role, Member], PermissionOverwrite]] = None,
277
default_auto_archive_duration: int = 1440,
278
default_thread_slowmode_delay: int = 0
279
) -> TextChannel:
280
"""
281
Create a text channel.
282
283
Parameters:
284
- name: Channel name
285
- reason: Audit log reason
286
- category: Parent category
287
- position: Channel position
288
- topic: Channel topic
289
- slowmode_delay: Slowmode delay in seconds
290
- nsfw: Whether channel is NSFW
291
- news: Create as announcement channel
292
- overwrites: Permission overwrites
293
- default_auto_archive_duration: Default thread archive duration
294
- default_thread_slowmode_delay: Default thread slowmode delay
295
296
Returns:
297
Created text channel
298
"""
299
300
async def create_voice_channel(
301
self,
302
name: str,
303
*,
304
reason: Optional[str] = None,
305
category: Optional[CategoryChannel] = None,
306
position: int = ...,
307
bitrate: int = 64000,
308
user_limit: int = 0,
309
overwrites: Optional[Dict[Union[Role, Member], PermissionOverwrite]] = None,
310
rtc_region: Optional[str] = None,
311
video_quality_mode: VideoQualityMode = VideoQualityMode.auto
312
) -> VoiceChannel:
313
"""
314
Create a voice channel.
315
316
Parameters:
317
- name: Channel name
318
- reason: Audit log reason
319
- category: Parent category
320
- position: Channel position
321
- bitrate: Audio bitrate
322
- user_limit: Maximum users (0 = unlimited)
323
- overwrites: Permission overwrites
324
- rtc_region: Voice region
325
- video_quality_mode: Video quality setting
326
327
Returns:
328
Created voice channel
329
"""
330
331
async def create_stage_channel(
332
self,
333
name: str,
334
*,
335
reason: Optional[str] = None,
336
category: Optional[CategoryChannel] = None,
337
position: int = ...,
338
bitrate: int = 64000,
339
overwrites: Optional[Dict[Union[Role, Member], PermissionOverwrite]] = None,
340
rtc_region: Optional[str] = None
341
) -> StageChannel:
342
"""
343
Create a stage channel.
344
345
Parameters:
346
- name: Channel name
347
- reason: Audit log reason
348
- category: Parent category
349
- position: Channel position
350
- bitrate: Audio bitrate
351
- overwrites: Permission overwrites
352
- rtc_region: Voice region
353
354
Returns:
355
Created stage channel
356
"""
357
358
async def create_category_channel(
359
self,
360
name: str,
361
*,
362
reason: Optional[str] = None,
363
position: int = ...,
364
overwrites: Optional[Dict[Union[Role, Member], PermissionOverwrite]] = None
365
) -> CategoryChannel:
366
"""
367
Create a category channel.
368
369
Parameters:
370
- name: Category name
371
- reason: Audit log reason
372
- position: Category position
373
- overwrites: Permission overwrites
374
375
Returns:
376
Created category channel
377
"""
378
379
async def create_forum_channel(
380
self,
381
name: str,
382
*,
383
reason: Optional[str] = None,
384
category: Optional[CategoryChannel] = None,
385
position: int = ...,
386
topic: Optional[str] = None,
387
slowmode_delay: int = 0,
388
nsfw: bool = False,
389
overwrites: Optional[Dict[Union[Role, Member], PermissionOverwrite]] = None,
390
default_auto_archive_duration: int = 1440,
391
default_thread_slowmode_delay: int = 0,
392
default_sort_order: Optional[ThreadSortOrder] = None,
393
default_layout: ThreadLayout = ThreadLayout.not_set,
394
available_tags: Optional[List[ForumTag]] = None,
395
default_reaction_emoji: Optional[Union[str, Emoji, PartialEmoji]] = None,
396
require_tag: bool = False
397
) -> ForumChannel:
398
"""
399
Create a forum channel.
400
401
Parameters:
402
- name: Channel name
403
- reason: Audit log reason
404
- category: Parent category
405
- position: Channel position
406
- topic: Channel topic/guidelines
407
- slowmode_delay: Slowmode delay in seconds
408
- nsfw: Whether channel is NSFW
409
- overwrites: Permission overwrites
410
- default_auto_archive_duration: Default thread archive duration
411
- default_thread_slowmode_delay: Default thread slowmode delay
412
- default_sort_order: Default thread sorting
413
- default_layout: Default thread layout
414
- available_tags: Available post tags
415
- default_reaction_emoji: Default reaction emoji
416
- require_tag: Require tag for posts
417
418
Returns:
419
Created forum channel
420
"""
421
```
422
423
### Role Management
424
425
Role creation, modification, and hierarchy management for guild permissions.
426
427
```python { .api }
428
class Guild:
429
async def create_role(
430
self,
431
*,
432
name: str = "new role",
433
permissions: Permissions = ...,
434
colour: Union[Colour, int] = ...,
435
color: Union[Colour, int] = ...,
436
hoist: bool = False,
437
display_icon: Optional[Union[bytes, str]] = None,
438
unicode_emoji: Optional[str] = None,
439
mentionable: bool = False,
440
reason: Optional[str] = None
441
) -> Role:
442
"""
443
Create a new role.
444
445
Parameters:
446
- name: Role name
447
- permissions: Role permissions
448
- colour/color: Role color
449
- hoist: Show separately in member list
450
- display_icon: Role icon bytes or unicode emoji
451
- unicode_emoji: Unicode emoji for role icon
452
- mentionable: Allow role mentions
453
- reason: Audit log reason
454
455
Returns:
456
Created role
457
"""
458
459
@property
460
def default_role(self) -> Role:
461
"""The @everyone role."""
462
463
@property
464
def premium_subscriber_role(self) -> Optional[Role]:
465
"""The Nitro booster role."""
466
467
@property
468
def self_role(self) -> Optional[Role]:
469
"""Bot's highest role."""
470
471
def get_member_named(self, name: str) -> Optional[Member]:
472
"""
473
Get member by name or name#discriminator.
474
475
Parameters:
476
- name: Member name or name#discriminator
477
478
Returns:
479
Member if found
480
"""
481
482
async def estimate_pruned_members(
483
self,
484
*,
485
days: int,
486
roles: List[Role] = ...
487
) -> int:
488
"""
489
Estimate members that would be pruned.
490
491
Parameters:
492
- days: Days of inactivity
493
- roles: Roles to include in prune
494
495
Returns:
496
Estimated prune count
497
"""
498
499
async def prune_members(
500
self,
501
*,
502
days: int,
503
compute_prune_count: bool = True,
504
roles: List[Role] = ...,
505
reason: Optional[str] = None
506
) -> Optional[int]:
507
"""
508
Prune inactive members.
509
510
Parameters:
511
- days: Days of inactivity
512
- compute_prune_count: Return prune count
513
- roles: Roles to include in prune
514
- reason: Audit log reason
515
516
Returns:
517
Number of members pruned if compute_prune_count is True
518
"""
519
520
async def fetch_emojis(self) -> List[Emoji]:
521
"""
522
Fetch all custom emojis.
523
524
Returns:
525
List of guild emojis
526
"""
527
528
async def fetch_emoji(self, emoji_id: int) -> Emoji:
529
"""
530
Fetch a specific emoji by ID.
531
532
Parameters:
533
- emoji_id: Emoji ID
534
535
Returns:
536
Emoji object
537
"""
538
539
async def create_custom_emoji(
540
self,
541
*,
542
name: str,
543
image: bytes,
544
roles: List[Role] = ...,
545
reason: Optional[str] = None
546
) -> Emoji:
547
"""
548
Create a custom emoji.
549
550
Parameters:
551
- name: Emoji name
552
- image: Emoji image bytes
553
- roles: Roles that can use emoji
554
- reason: Audit log reason
555
556
Returns:
557
Created emoji
558
"""
559
560
async def fetch_stickers(self) -> List[GuildSticker]:
561
"""
562
Fetch all guild stickers.
563
564
Returns:
565
List of guild stickers
566
"""
567
568
async def fetch_sticker(self, sticker_id: int) -> GuildSticker:
569
"""
570
Fetch a specific sticker by ID.
571
572
Parameters:
573
- sticker_id: Sticker ID
574
575
Returns:
576
Sticker object
577
"""
578
579
async def create_sticker(
580
self,
581
*,
582
name: str,
583
description: str,
584
emoji: str,
585
file: File,
586
reason: Optional[str] = None
587
) -> GuildSticker:
588
"""
589
Create a custom sticker.
590
591
Parameters:
592
- name: Sticker name
593
- description: Sticker description
594
- emoji: Related unicode emoji
595
- file: Sticker image file
596
- reason: Audit log reason
597
598
Returns:
599
Created sticker
600
"""
601
```
602
603
### Guild Features
604
605
Advanced guild features including scheduled events, moderation, and community features.
606
607
```python { .api }
608
class GuildScheduledEvent:
609
def __init__(self): ...
610
611
id: int
612
guild_id: int
613
channel_id: Optional[int]
614
creator_id: Optional[int]
615
name: str
616
description: Optional[str]
617
scheduled_start_time: datetime
618
scheduled_end_time: Optional[datetime]
619
privacy_level: GuildScheduledEventPrivacyLevel
620
status: GuildScheduledEventStatus
621
entity_type: GuildScheduledEventEntityType
622
entity_id: Optional[int]
623
entity_metadata: Optional[GuildScheduledEventMetadata]
624
creator: Optional[User]
625
user_count: Optional[int]
626
image: Optional[Asset]
627
628
@property
629
def guild(self) -> Optional[Guild]:
630
"""Guild the event belongs to."""
631
632
@property
633
def channel(self) -> Optional[GuildChannel]:
634
"""Channel the event is in."""
635
636
@property
637
def cover_image(self) -> Optional[Asset]:
638
"""Event cover image."""
639
640
async def edit(
641
self,
642
*,
643
name: str = ...,
644
description: Optional[str] = ...,
645
channel: Optional[GuildChannel] = ...,
646
privacy_level: GuildScheduledEventPrivacyLevel = ...,
647
status: GuildScheduledEventStatus = ...,
648
entity_type: GuildScheduledEventEntityType = ...,
649
scheduled_start_time: datetime = ...,
650
scheduled_end_time: Optional[datetime] = ...,
651
location: Optional[str] = ...,
652
image: Optional[bytes] = ...,
653
reason: Optional[str] = None
654
) -> GuildScheduledEvent:
655
"""
656
Edit the scheduled event.
657
658
Parameters:
659
- name: Event name
660
- description: Event description
661
- channel: Event channel
662
- privacy_level: Event privacy
663
- status: Event status
664
- entity_type: Event entity type
665
- scheduled_start_time: Start time
666
- scheduled_end_time: End time
667
- location: Event location (for external events)
668
- image: Event cover image
669
- reason: Audit log reason
670
671
Returns:
672
Updated event
673
"""
674
675
async def delete(self, *, reason: Optional[str] = None) -> None:
676
"""
677
Delete the scheduled event.
678
679
Parameters:
680
- reason: Audit log reason
681
"""
682
683
async def start(self, *, reason: Optional[str] = None) -> GuildScheduledEvent:
684
"""
685
Start the scheduled event.
686
687
Parameters:
688
- reason: Audit log reason
689
690
Returns:
691
Updated event
692
"""
693
694
async def end(self, *, reason: Optional[str] = None) -> GuildScheduledEvent:
695
"""
696
End the scheduled event.
697
698
Parameters:
699
- reason: Audit log reason
700
701
Returns:
702
Updated event
703
"""
704
705
class Guild:
706
async def fetch_scheduled_events(self) -> List[GuildScheduledEvent]:
707
"""
708
Fetch all scheduled events.
709
710
Returns:
711
List of scheduled events
712
"""
713
714
async def fetch_scheduled_event(self, event_id: int) -> GuildScheduledEvent:
715
"""
716
Fetch a specific scheduled event.
717
718
Parameters:
719
- event_id: Event ID
720
721
Returns:
722
Scheduled event
723
"""
724
725
async def create_scheduled_event(
726
self,
727
*,
728
name: str,
729
description: Optional[str] = None,
730
channel: Optional[GuildChannel] = None,
731
privacy_level: GuildScheduledEventPrivacyLevel = GuildScheduledEventPrivacyLevel.guild_only,
732
scheduled_start_time: datetime,
733
scheduled_end_time: Optional[datetime] = None,
734
entity_type: GuildScheduledEventEntityType = GuildScheduledEventEntityType.stage_instance,
735
location: Optional[str] = None,
736
image: Optional[bytes] = None,
737
reason: Optional[str] = None
738
) -> GuildScheduledEvent:
739
"""
740
Create a scheduled event.
741
742
Parameters:
743
- name: Event name
744
- description: Event description
745
- channel: Event channel
746
- privacy_level: Event privacy
747
- scheduled_start_time: Start time
748
- scheduled_end_time: End time
749
- entity_type: Event entity type
750
- location: Event location (for external events)
751
- image: Event cover image
752
- reason: Audit log reason
753
754
Returns:
755
Created event
756
"""
757
758
async def fetch_bans(self, *, limit: Optional[int] = None, before: Optional[Snowflake] = None, after: Optional[Snowflake] = None) -> AsyncIterator[BanEntry]:
759
"""
760
Fetch guild bans.
761
762
Parameters:
763
- limit: Maximum bans to fetch
764
- before: Fetch bans before this user
765
- after: Fetch bans after this user
766
767
Yields:
768
Ban entries
769
"""
770
771
async def fetch_ban(self, user: Snowflake) -> BanEntry:
772
"""
773
Fetch a specific ban.
774
775
Parameters:
776
- user: Banned user
777
778
Returns:
779
Ban entry
780
"""
781
782
async def fetch_invites(self) -> List[Invite]:
783
"""
784
Fetch all guild invites.
785
786
Returns:
787
List of invites
788
"""
789
790
async def fetch_integrations(self) -> List[Integration]:
791
"""
792
Fetch guild integrations.
793
794
Returns:
795
List of integrations
796
"""
797
798
async def fetch_webhooks(self) -> List[Webhook]:
799
"""
800
Fetch guild webhooks.
801
802
Returns:
803
List of webhooks
804
"""
805
806
async def audit_logs(
807
self,
808
*,
809
limit: int = 100,
810
before: Optional[Union[Snowflake, AuditLogEntry, datetime]] = None,
811
after: Optional[Union[Snowflake, AuditLogEntry, datetime]] = None,
812
oldest_first: Optional[bool] = None,
813
user: Optional[Snowflake] = None,
814
action: Optional[AuditLogAction] = None
815
) -> AsyncIterator[AuditLogEntry]:
816
"""
817
Fetch audit log entries.
818
819
Parameters:
820
- limit: Maximum entries to fetch
821
- before: Fetch entries before this entry/time
822
- after: Fetch entries after this entry/time
823
- oldest_first: Sort order
824
- user: Filter by user
825
- action: Filter by action type
826
827
Yields:
828
Audit log entries
829
"""
830
831
async def widget(self) -> Widget:
832
"""
833
Fetch guild widget.
834
835
Returns:
836
Guild widget
837
"""
838
839
async def chunk(self, *, cache: bool = True) -> List[Member]:
840
"""
841
Request all members from Discord.
842
843
Parameters:
844
- cache: Whether to cache members
845
846
Returns:
847
List of all members
848
"""
849
850
async def query_members(
851
self,
852
query: Optional[str] = None,
853
*,
854
limit: int = 5,
855
user_ids: Optional[List[int]] = None,
856
cache: bool = True
857
) -> List[Member]:
858
"""
859
Query guild members.
860
861
Parameters:
862
- query: Username query
863
- limit: Maximum members to return
864
- user_ids: Specific user IDs to fetch
865
- cache: Whether to cache members
866
867
Returns:
868
List of matching members
869
"""
870
871
async def change_voice_state(
872
self,
873
*,
874
channel: Optional[VoiceChannel],
875
self_mute: bool = False,
876
self_deaf: bool = False
877
) -> None:
878
"""
879
Change bot's voice state.
880
881
Parameters:
882
- channel: Voice channel to join (None to disconnect)
883
- self_mute: Whether to self-mute
884
- self_deaf: Whether to self-deafen
885
"""
886
```
887
888
### Guild Builder
889
890
Helper class for creating guilds with predefined structure.
891
892
```python { .api }
893
class GuildBuilder:
894
def __init__(self, name: str):
895
"""
896
Initialize guild builder.
897
898
Parameters:
899
- name: Guild name
900
"""
901
902
def add_text_channel(
903
self,
904
name: str,
905
*,
906
category: Optional[str] = None,
907
topic: Optional[str] = None,
908
nsfw: bool = False,
909
slowmode_delay: int = 0,
910
permissions: Optional[Dict[str, PermissionOverwrite]] = None
911
) -> GuildBuilder:
912
"""
913
Add a text channel to the guild.
914
915
Parameters:
916
- name: Channel name
917
- category: Parent category name
918
- topic: Channel topic
919
- nsfw: Whether channel is NSFW
920
- slowmode_delay: Slowmode delay
921
- permissions: Permission overwrites by role name
922
923
Returns:
924
Guild builder for chaining
925
"""
926
927
def add_voice_channel(
928
self,
929
name: str,
930
*,
931
category: Optional[str] = None,
932
bitrate: int = 64000,
933
user_limit: int = 0,
934
permissions: Optional[Dict[str, PermissionOverwrite]] = None
935
) -> GuildBuilder:
936
"""
937
Add a voice channel to the guild.
938
939
Parameters:
940
- name: Channel name
941
- category: Parent category name
942
- bitrate: Audio bitrate
943
- user_limit: User limit
944
- permissions: Permission overwrites by role name
945
946
Returns:
947
Guild builder for chaining
948
"""
949
950
def add_category(
951
self,
952
name: str,
953
*,
954
permissions: Optional[Dict[str, PermissionOverwrite]] = None
955
) -> GuildBuilder:
956
"""
957
Add a category channel to the guild.
958
959
Parameters:
960
- name: Category name
961
- permissions: Permission overwrites by role name
962
963
Returns:
964
Guild builder for chaining
965
"""
966
967
def add_role(
968
self,
969
name: str,
970
*,
971
permissions: Optional[Permissions] = None,
972
color: Optional[Union[Colour, int]] = None,
973
hoist: bool = False,
974
mentionable: bool = False
975
) -> GuildBuilder:
976
"""
977
Add a role to the guild.
978
979
Parameters:
980
- name: Role name
981
- permissions: Role permissions
982
- color: Role color
983
- hoist: Show separately in member list
984
- mentionable: Allow mentions
985
986
Returns:
987
Guild builder for chaining
988
"""
989
990
async def create(self, *, icon: Optional[bytes] = None) -> Guild:
991
"""
992
Create the guild with configured structure.
993
994
Parameters:
995
- icon: Guild icon bytes
996
997
Returns:
998
Created guild
999
"""
1000
```
1001
1002
## Usage Examples
1003
1004
### Basic Guild Management
1005
1006
```python
1007
import disnake
1008
from disnake.ext import commands
1009
1010
bot = commands.Bot(command_prefix='!', intents=disnake.Intents.all())
1011
1012
@bot.command()
1013
async def serverinfo(ctx):
1014
"""Display server information."""
1015
guild = ctx.guild
1016
1017
embed = disnake.Embed(title=guild.name, color=0x00ff00)
1018
embed.set_thumbnail(url=guild.icon.url if guild.icon else None)
1019
1020
embed.add_field(name="Owner", value=guild.owner.mention, inline=True)
1021
embed.add_field(name="Members", value=guild.member_count, inline=True)
1022
embed.add_field(name="Channels", value=len(guild.channels), inline=True)
1023
embed.add_field(name="Roles", value=len(guild.roles), inline=True)
1024
embed.add_field(name="Boost Level", value=guild.premium_tier, inline=True)
1025
embed.add_field(name="Boosts", value=guild.premium_subscription_count or 0, inline=True)
1026
1027
await ctx.send(embed=embed)
1028
1029
@bot.command()
1030
async def createchannel(ctx, channel_type: str, *, name: str):
1031
"""Create a new channel."""
1032
if not ctx.author.guild_permissions.manage_channels:
1033
return await ctx.send("You don't have permission to manage channels.")
1034
1035
guild = ctx.guild
1036
1037
if channel_type.lower() == "text":
1038
channel = await guild.create_text_channel(name)
1039
await ctx.send(f"Created text channel: {channel.mention}")
1040
elif channel_type.lower() == "voice":
1041
channel = await guild.create_voice_channel(name)
1042
await ctx.send(f"Created voice channel: {channel.name}")
1043
elif channel_type.lower() == "category":
1044
channel = await guild.create_category_channel(name)
1045
await ctx.send(f"Created category: {channel.name}")
1046
else:
1047
await ctx.send("Invalid channel type. Use: text, voice, or category")
1048
```
1049
1050
### Member Management
1051
1052
```python
1053
@bot.command()
1054
async def ban(ctx, member: disnake.Member, *, reason="No reason provided"):
1055
"""Ban a member from the server."""
1056
if not ctx.author.guild_permissions.ban_members:
1057
return await ctx.send("You don't have permission to ban members.")
1058
1059
if member.top_role >= ctx.author.top_role:
1060
return await ctx.send("You cannot ban this member.")
1061
1062
await ctx.guild.ban(member, reason=reason)
1063
await ctx.send(f"Banned {member} for: {reason}")
1064
1065
@bot.command()
1066
async def kick(ctx, member: disnake.Member, *, reason="No reason provided"):
1067
"""Kick a member from the server."""
1068
if not ctx.author.guild_permissions.kick_members:
1069
return await ctx.send("You don't have permission to kick members.")
1070
1071
if member.top_role >= ctx.author.top_role:
1072
return await ctx.send("You cannot kick this member.")
1073
1074
await ctx.guild.kick(member, reason=reason)
1075
await ctx.send(f"Kicked {member} for: {reason}")
1076
1077
@bot.command()
1078
async def unban(ctx, user_id: int):
1079
"""Unban a user by ID."""
1080
if not ctx.author.guild_permissions.ban_members:
1081
return await ctx.send("You don't have permission to unban members.")
1082
1083
user = disnake.Object(id=user_id)
1084
await ctx.guild.unban(user)
1085
await ctx.send(f"Unbanned user with ID {user_id}")
1086
1087
@bot.command()
1088
async def prune(ctx, days: int = 7):
1089
"""Prune inactive members."""
1090
if not ctx.author.guild_permissions.kick_members:
1091
return await ctx.send("You don't have permission to prune members.")
1092
1093
if not 1 <= days <= 30:
1094
return await ctx.send("Days must be between 1 and 30.")
1095
1096
# Estimate prune count first
1097
count = await ctx.guild.estimate_pruned_members(days=days)
1098
1099
if count == 0:
1100
return await ctx.send("No members would be pruned.")
1101
1102
# Confirm with user
1103
await ctx.send(f"This will prune {count} members. React with β to confirm.")
1104
1105
def check(reaction, user):
1106
return user == ctx.author and str(reaction.emoji) == 'β '
1107
1108
try:
1109
await bot.wait_for('reaction_add', timeout=30.0, check=check)
1110
pruned = await ctx.guild.prune_members(days=days)
1111
await ctx.send(f"Pruned {pruned} members.")
1112
except asyncio.TimeoutError:
1113
await ctx.send("Prune cancelled - no confirmation received.")
1114
```
1115
1116
### Role Management
1117
1118
```python
1119
@bot.command()
1120
async def createrole(ctx, *, name: str):
1121
"""Create a new role."""
1122
if not ctx.author.guild_permissions.manage_roles:
1123
return await ctx.send("You don't have permission to manage roles.")
1124
1125
role = await ctx.guild.create_role(name=name, reason=f"Created by {ctx.author}")
1126
await ctx.send(f"Created role: {role.mention}")
1127
1128
@bot.command()
1129
async def giverole(ctx, member: disnake.Member, role: disnake.Role):
1130
"""Give a role to a member."""
1131
if not ctx.author.guild_permissions.manage_roles:
1132
return await ctx.send("You don't have permission to manage roles.")
1133
1134
if role >= ctx.author.top_role:
1135
return await ctx.send("You cannot assign this role.")
1136
1137
if role in member.roles:
1138
return await ctx.send(f"{member} already has the {role.name} role.")
1139
1140
await member.add_roles(role, reason=f"Added by {ctx.author}")
1141
await ctx.send(f"Gave {role.name} to {member.mention}")
1142
1143
@bot.command()
1144
async def removerole(ctx, member: disnake.Member, role: disnake.Role):
1145
"""Remove a role from a member."""
1146
if not ctx.author.guild_permissions.manage_roles:
1147
return await ctx.send("You don't have permission to manage roles.")
1148
1149
if role >= ctx.author.top_role:
1150
return await ctx.send("You cannot manage this role.")
1151
1152
if role not in member.roles:
1153
return await ctx.send(f"{member} doesn't have the {role.name} role.")
1154
1155
await member.remove_roles(role, reason=f"Removed by {ctx.author}")
1156
await ctx.send(f"Removed {role.name} from {member.mention}")
1157
```
1158
1159
### Scheduled Events
1160
1161
```python
1162
from datetime import datetime, timedelta
1163
1164
@bot.slash_command(description="Create a scheduled event")
1165
async def create_event(
1166
inter: disnake.ApplicationCommandInteraction,
1167
name: str,
1168
description: str,
1169
channel: disnake.VoiceChannel,
1170
start_time: str, # Format: "YYYY-MM-DD HH:MM"
1171
duration_hours: int = 2
1172
):
1173
"""Create a scheduled event in a voice channel."""
1174
if not inter.author.guild_permissions.manage_events:
1175
return await inter.response.send_message("You don't have permission to manage events.")
1176
1177
try:
1178
# Parse start time
1179
start_dt = datetime.strptime(start_time, "%Y-%m-%d %H:%M")
1180
end_dt = start_dt + timedelta(hours=duration_hours)
1181
1182
event = await inter.guild.create_scheduled_event(
1183
name=name,
1184
description=description,
1185
channel=channel,
1186
scheduled_start_time=start_dt,
1187
scheduled_end_time=end_dt,
1188
entity_type=disnake.GuildScheduledEventEntityType.voice,
1189
reason=f"Created by {inter.author}"
1190
)
1191
1192
await inter.response.send_message(f"Created event: **{event.name}**\nStarts: <t:{int(start_dt.timestamp())}:F>")
1193
1194
except ValueError:
1195
await inter.response.send_message("Invalid time format. Use: YYYY-MM-DD HH:MM")
1196
1197
@bot.slash_command(description="List upcoming events")
1198
async def events(inter: disnake.ApplicationCommandInteraction):
1199
"""List all scheduled events."""
1200
events = await inter.guild.fetch_scheduled_events()
1201
1202
if not events:
1203
return await inter.response.send_message("No scheduled events found.")
1204
1205
embed = disnake.Embed(title=f"Scheduled Events in {inter.guild.name}", color=0x00ff00)
1206
1207
for event in events:
1208
status_emoji = {
1209
disnake.GuildScheduledEventStatus.scheduled: "π ",
1210
disnake.GuildScheduledEventStatus.active: "π΄",
1211
disnake.GuildScheduledEventStatus.completed: "β ",
1212
disnake.GuildScheduledEventStatus.cancelled: "β"
1213
}
1214
1215
embed.add_field(
1216
name=f"{status_emoji.get(event.status, 'π ')} {event.name}",
1217
value=f"<t:{int(event.scheduled_start_time.timestamp())}:F>",
1218
inline=False
1219
)
1220
1221
await inter.response.send_message(embed=embed)
1222
```
1223
1224
### Advanced Guild Setup
1225
1226
```python
1227
@bot.command()
1228
async def setup_server(ctx):
1229
"""Set up a complete server structure."""
1230
if not ctx.author.guild_permissions.administrator:
1231
return await ctx.send("You need Administrator permission to set up the server.")
1232
1233
guild = ctx.guild
1234
1235
# Create roles
1236
roles = {
1237
"Moderator": {"color": 0xff0000, "permissions": disnake.Permissions(moderate_members=True, manage_messages=True)},
1238
"Helper": {"color": 0x00ff00, "permissions": disnake.Permissions(manage_messages=True)},
1239
"Member": {"color": 0x0099ff, "permissions": disnake.Permissions.none()}
1240
}
1241
1242
created_roles = {}
1243
for role_name, role_config in roles.items():
1244
role = await guild.create_role(
1245
name=role_name,
1246
color=role_config["color"],
1247
permissions=role_config["permissions"],
1248
reason="Server setup"
1249
)
1250
created_roles[role_name] = role
1251
await ctx.send(f"Created role: {role.mention}")
1252
1253
# Create categories and channels
1254
# General category
1255
general_cat = await guild.create_category_channel("General")
1256
await guild.create_text_channel("general", category=general_cat)
1257
await guild.create_text_channel("announcements", category=general_cat)
1258
await guild.create_voice_channel("General Voice", category=general_cat)
1259
1260
# Staff category with permissions
1261
staff_overwrites = {
1262
guild.default_role: disnake.PermissionOverwrite(view_channel=False),
1263
created_roles["Moderator"]: disnake.PermissionOverwrite(view_channel=True),
1264
created_roles["Helper"]: disnake.PermissionOverwrite(view_channel=True)
1265
}
1266
1267
staff_cat = await guild.create_category_channel("Staff", overwrites=staff_overwrites)
1268
await guild.create_text_channel("staff-chat", category=staff_cat)
1269
await guild.create_text_channel("moderation-logs", category=staff_cat)
1270
1271
await ctx.send("β Server setup complete!")
1272
```