0
# Commands and Interactions
1
2
Modern Discord application commands (slash commands, user commands, message commands) and comprehensive interaction handling. This system provides the foundation for creating interactive Discord applications with rich command interfaces.
3
4
## Capabilities
5
6
### Application Commands
7
8
Application commands are Discord's modern command system, providing slash commands, context menu commands, and rich interaction capabilities.
9
10
```python { .api }
11
def slash_command(
12
*,
13
name: str = None,
14
description: str = None,
15
guild_ids: List[int] = None,
16
name_localizations: Dict[str, str] = None,
17
description_localizations: Dict[str, str] = None,
18
default_member_permissions: Optional[Permissions] = None,
19
dm_permission: bool = True,
20
nsfw: bool = False,
21
**kwargs
22
) -> Callable:
23
"""
24
Create a slash command.
25
26
Parameters:
27
- name: str - Command name (1-32 characters, lowercase)
28
- description: str - Command description (1-100 characters)
29
- guild_ids: List[int] - Guilds where command is available
30
- name_localizations: Dict[str, str] - Localized names
31
- description_localizations: Dict[str, str] - Localized descriptions
32
- default_member_permissions: Permissions - Default permissions required
33
- dm_permission: bool - Whether command works in DMs
34
- nsfw: bool - Whether command is age-restricted
35
"""
36
37
def user_command(
38
*,
39
name: str = None,
40
guild_ids: List[int] = None,
41
name_localizations: Dict[str, str] = None,
42
default_member_permissions: Optional[Permissions] = None,
43
dm_permission: bool = True,
44
nsfw: bool = False,
45
**kwargs
46
) -> Callable:
47
"""
48
Create a user context menu command.
49
50
Parameters:
51
- name: str - Command name
52
- guild_ids: List[int] - Guilds where command is available
53
- name_localizations: Dict[str, str] - Localized names
54
- default_member_permissions: Permissions - Default permissions required
55
- dm_permission: bool - Whether command works in DMs
56
- nsfw: bool - Whether command is age-restricted
57
"""
58
59
def message_command(
60
*,
61
name: str = None,
62
guild_ids: List[int] = None,
63
name_localizations: Dict[str, str] = None,
64
default_member_permissions: Optional[Permissions] = None,
65
dm_permission: bool = True,
66
nsfw: bool = False,
67
**kwargs
68
) -> Callable:
69
"""
70
Create a message context menu command.
71
72
Parameters:
73
- name: str - Command name
74
- guild_ids: List[int] - Guilds where command is available
75
- name_localizations: Dict[str, str] - Localized names
76
- default_member_permissions: Permissions - Default permissions required
77
- dm_permission: bool - Whether command works in DMs
78
- nsfw: bool - Whether command is age-restricted
79
"""
80
81
class ApplicationCommand:
82
"""
83
Base class for application commands.
84
"""
85
86
@property
87
def id(self) -> Optional[int]:
88
"""The command's ID after registration."""
89
90
@property
91
def name(self) -> str:
92
"""The command name."""
93
94
@property
95
def description(self) -> str:
96
"""The command description."""
97
98
@property
99
def type(self) -> ApplicationCommandType:
100
"""The command type."""
101
102
@property
103
def guild_ids(self) -> Optional[List[int]]:
104
"""Guilds where the command is available."""
105
106
@property
107
def default_member_permissions(self) -> Optional[Permissions]:
108
"""Default permissions required."""
109
110
@property
111
def dm_permission(self) -> bool:
112
"""Whether the command works in DMs."""
113
114
@property
115
def nsfw(self) -> bool:
116
"""Whether the command is age-restricted."""
117
118
class SlashCommand(ApplicationCommand):
119
"""
120
Represents a slash command.
121
"""
122
123
@property
124
def options(self) -> List[Option]:
125
"""The command's options."""
126
127
@property
128
def cog(self) -> Optional[Cog]:
129
"""The cog this command belongs to."""
130
131
def add_option(self, option: Option) -> None:
132
"""Add an option to the command."""
133
134
def remove_option(self, name: str) -> Optional[Option]:
135
"""Remove an option from the command."""
136
137
class SlashCommandGroup(ApplicationCommand):
138
"""
139
Represents a group of slash commands.
140
"""
141
142
@property
143
def subcommands(self) -> List[SlashCommand]:
144
"""Subcommands in this group."""
145
146
def command(
147
self,
148
*,
149
name: str = None,
150
description: str = None,
151
**kwargs
152
) -> Callable:
153
"""Add a subcommand to the group."""
154
155
def create_subgroup(
156
self,
157
name: str,
158
description: str,
159
**kwargs
160
) -> SlashCommandGroup:
161
"""Create a subgroup within this group."""
162
163
class ContextMenuCommand(ApplicationCommand):
164
"""
165
Base class for context menu commands.
166
"""
167
pass
168
169
class UserCommand(ContextMenuCommand):
170
"""
171
Represents a user context menu command.
172
"""
173
pass
174
175
class MessageCommand(ContextMenuCommand):
176
"""
177
Represents a message context menu command.
178
"""
179
pass
180
```
181
182
### Command Options and Parameters
183
184
Options define the parameters that users can provide to slash commands.
185
186
```python { .api }
187
class Option:
188
"""
189
Represents a slash command option.
190
"""
191
192
def __init__(
193
self,
194
input_type: SlashCommandOptionType,
195
/,
196
description: str,
197
*,
198
name: str = None,
199
name_localizations: Dict[str, str] = None,
200
description_localizations: Dict[str, str] = None,
201
required: bool = True,
202
default: Any = None,
203
choices: List[OptionChoice] = None,
204
channel_types: List[ChannelType] = None,
205
min_value: Union[int, float] = None,
206
max_value: Union[int, float] = None,
207
min_length: int = None,
208
max_length: int = None,
209
autocomplete: bool = False,
210
**kwargs
211
) -> None:
212
"""
213
Create a command option.
214
215
Parameters:
216
- input_type: SlashCommandOptionType - The option type
217
- description: str - Option description
218
- name: str - Option name (defaults to parameter name)
219
- name_localizations: Dict[str, str] - Localized names
220
- description_localizations: Dict[str, str] - Localized descriptions
221
- required: bool - Whether the option is required
222
- default: Any - Default value if not provided
223
- choices: List[OptionChoice] - Predefined choices
224
- channel_types: List[ChannelType] - Allowed channel types
225
- min_value: Union[int, float] - Minimum numeric value
226
- max_value: Union[int, float] - Maximum numeric value
227
- min_length: int - Minimum string length
228
- max_length: int - Maximum string length
229
- autocomplete: bool - Whether to enable autocomplete
230
"""
231
232
@property
233
def name(self) -> str: ...
234
@property
235
def description(self) -> str: ...
236
@property
237
def type(self) -> SlashCommandOptionType: ...
238
@property
239
def required(self) -> bool: ...
240
@property
241
def choices(self) -> Optional[List[OptionChoice]]: ...
242
@property
243
def channel_types(self) -> Optional[List[ChannelType]]: ...
244
@property
245
def min_value(self) -> Optional[Union[int, float]]: ...
246
@property
247
def max_value(self) -> Optional[Union[int, float]]: ...
248
@property
249
def min_length(self) -> Optional[int]: ...
250
@property
251
def max_length(self) -> Optional[int]: ...
252
@property
253
def autocomplete(self) -> bool: ...
254
255
class OptionChoice:
256
"""
257
Represents a predefined choice for a command option.
258
"""
259
260
def __init__(
261
self,
262
name: str,
263
value: Union[str, int, float],
264
*,
265
name_localizations: Dict[str, str] = None
266
) -> None:
267
"""
268
Create an option choice.
269
270
Parameters:
271
- name: str - Choice display name
272
- value: Union[str, int, float] - Choice value
273
- name_localizations: Dict[str, str] - Localized names
274
"""
275
276
@property
277
def name(self) -> str: ...
278
@property
279
def value(self) -> Union[str, int, float]: ...
280
@property
281
def name_localizations(self) -> Optional[Dict[str, str]]: ...
282
283
def option(
284
name: str = None,
285
*,
286
description: str = None,
287
input_type: SlashCommandOptionType = None,
288
required: bool = None,
289
default: Any = None,
290
choices: List[Union[OptionChoice, str, int, float]] = None,
291
autocomplete: bool = None,
292
**kwargs
293
) -> Callable:
294
"""
295
Decorator to define a command option inline.
296
297
Parameters:
298
- name: str - Option name
299
- description: str - Option description
300
- input_type: SlashCommandOptionType - Option type
301
- required: bool - Whether required
302
- default: Any - Default value
303
- choices: List - Predefined choices
304
- autocomplete: bool - Enable autocomplete
305
"""
306
307
class ThreadOption:
308
"""
309
Special option for thread selection.
310
"""
311
312
def __init__(
313
self,
314
description: str,
315
*,
316
name: str = None,
317
required: bool = True
318
) -> None: ...
319
```
320
321
### Application Context and Interaction Handling
322
323
Context objects provide access to interaction data and methods for responding to users.
324
325
```python { .api }
326
class ApplicationContext:
327
"""
328
Represents the context for an application command.
329
"""
330
331
@property
332
def bot(self) -> Bot:
333
"""The bot instance."""
334
335
@property
336
def interaction(self) -> Interaction:
337
"""The underlying interaction."""
338
339
@property
340
def command(self) -> ApplicationCommand:
341
"""The command being invoked."""
342
343
@property
344
def user(self) -> Union[User, Member]:
345
"""The user who invoked the command."""
346
347
@property
348
def author(self) -> Union[User, Member]:
349
"""Alias for user."""
350
351
@property
352
def guild(self) -> Optional[Guild]:
353
"""The guild where the command was invoked."""
354
355
@property
356
def channel(self) -> Union[GuildChannel, DMChannel, PartialMessageable]:
357
"""The channel where the command was invoked."""
358
359
@property
360
def guild_id(self) -> Optional[int]:
361
"""The guild ID."""
362
363
@property
364
def channel_id(self) -> int:
365
"""The channel ID."""
366
367
@property
368
def locale(self) -> str:
369
"""The user's locale."""
370
371
@property
372
def guild_locale(self) -> Optional[str]:
373
"""The guild's locale."""
374
375
@property
376
def created_at(self) -> datetime:
377
"""When the interaction was created."""
378
379
@property
380
def selected_options(self) -> Dict[str, Any]:
381
"""Selected command options."""
382
383
def get_parameter(self, name: str) -> Any:
384
"""Get a parameter value by name."""
385
386
async def respond(
387
self,
388
content: str = None,
389
*,
390
embed: Embed = None,
391
embeds: List[Embed] = None,
392
view: View = None,
393
tts: bool = False,
394
ephemeral: bool = False,
395
allowed_mentions: AllowedMentions = None,
396
file: File = None,
397
files: List[File] = None,
398
suppress_embeds: bool = False,
399
**kwargs
400
) -> Union[Interaction, InteractionMessage]:
401
"""
402
Respond to the interaction.
403
404
Parameters:
405
- content: str - Response content
406
- embed: Embed - Rich embed
407
- embeds: List[Embed] - Multiple embeds
408
- view: View - UI components
409
- tts: bool - Text-to-speech
410
- ephemeral: bool - Whether response is ephemeral
411
- allowed_mentions: AllowedMentions - Mention settings
412
- file: File - File attachment
413
- files: List[File] - Multiple files
414
- suppress_embeds: bool - Suppress embeds
415
"""
416
417
async def defer(self, *, ephemeral: bool = False, invisible: bool = True) -> None:
418
"""
419
Defer the interaction response.
420
421
Parameters:
422
- ephemeral: bool - Whether the deferred response is ephemeral
423
- invisible: bool - Whether to show a loading state
424
"""
425
426
async def followup(
427
self,
428
content: str = None,
429
*,
430
embed: Embed = None,
431
embeds: List[Embed] = None,
432
view: View = None,
433
tts: bool = False,
434
ephemeral: bool = False,
435
file: File = None,
436
files: List[File] = None,
437
**kwargs
438
) -> InteractionMessage:
439
"""Send a followup message after responding or deferring."""
440
441
async def edit(
442
self,
443
*,
444
content: str = None,
445
embed: Embed = None,
446
embeds: List[Embed] = None,
447
view: View = None,
448
file: File = None,
449
files: List[File] = None,
450
**kwargs
451
) -> InteractionMessage:
452
"""Edit the original interaction response."""
453
454
async def delete(self, *, delay: float = None) -> None:
455
"""Delete the original interaction response."""
456
457
async def send_modal(self, modal: Modal) -> None:
458
"""Send a modal dialog in response to the interaction."""
459
460
class AutocompleteContext:
461
"""
462
Context for autocomplete interactions.
463
"""
464
465
@property
466
def bot(self) -> Bot: ...
467
@property
468
def interaction(self) -> Interaction: ...
469
@property
470
def user(self) -> Union[User, Member]: ...
471
@property
472
def guild(self) -> Optional[Guild]: ...
473
@property
474
def channel(self) -> Union[GuildChannel, DMChannel]: ...
475
@property
476
def focused(self) -> Option:
477
"""The option being autocompleted."""
478
479
@property
480
def value(self) -> str:
481
"""The current input value."""
482
483
@property
484
def options(self) -> Dict[str, Any]:
485
"""All current option values."""
486
487
async def send_choices(
488
self,
489
choices: Union[List[OptionChoice], List[str], List[int], List[float]]
490
) -> None:
491
"""Send autocomplete choices."""
492
```
493
494
### Interaction Objects
495
496
Core interaction classes that handle Discord's interaction system.
497
498
```python { .api }
499
class Interaction:
500
"""
501
Represents a Discord interaction.
502
"""
503
504
@property
505
def id(self) -> int:
506
"""The interaction ID."""
507
508
@property
509
def type(self) -> InteractionType:
510
"""The interaction type."""
511
512
@property
513
def data(self) -> Optional[Dict[str, Any]]:
514
"""The interaction data."""
515
516
@property
517
def guild_id(self) -> Optional[int]:
518
"""The guild ID."""
519
520
@property
521
def guild(self) -> Optional[Guild]:
522
"""The guild."""
523
524
@property
525
def channel_id(self) -> Optional[int]:
526
"""The channel ID."""
527
528
@property
529
def channel(self) -> Optional[Union[GuildChannel, DMChannel, PartialMessageable]]:
530
"""The channel."""
531
532
@property
533
def user(self) -> Union[User, Member]:
534
"""The user who created the interaction."""
535
536
@property
537
def message(self) -> Optional[Message]:
538
"""The message associated with the interaction."""
539
540
@property
541
def token(self) -> str:
542
"""The interaction token."""
543
544
@property
545
def version(self) -> int:
546
"""The interaction version."""
547
548
@property
549
def application_id(self) -> int:
550
"""The application ID."""
551
552
@property
553
def locale(self) -> str:
554
"""The user's locale."""
555
556
@property
557
def guild_locale(self) -> Optional[str]:
558
"""The guild's locale."""
559
560
@property
561
def created_at(self) -> datetime:
562
"""When the interaction was created."""
563
564
@property
565
def expires_at(self) -> datetime:
566
"""When the interaction expires."""
567
568
@property
569
def is_expired(self) -> bool:
570
"""Whether the interaction has expired."""
571
572
@property
573
def response(self) -> InteractionResponse:
574
"""The interaction response handler."""
575
576
async def original_response(self) -> InteractionMessage:
577
"""Get the original interaction response."""
578
579
async def edit_original_response(
580
self,
581
*,
582
content: str = None,
583
embed: Embed = None,
584
embeds: List[Embed] = None,
585
view: View = None,
586
file: File = None,
587
files: List[File] = None,
588
**kwargs
589
) -> InteractionMessage:
590
"""Edit the original response."""
591
592
async def delete_original_response(self) -> None:
593
"""Delete the original response."""
594
595
async def followup(
596
self,
597
content: str = None,
598
*,
599
embed: Embed = None,
600
embeds: List[Embed] = None,
601
view: View = None,
602
tts: bool = False,
603
ephemeral: bool = False,
604
file: File = None,
605
files: List[File] = None,
606
**kwargs
607
) -> InteractionMessage:
608
"""Send a followup message."""
609
610
class InteractionResponse:
611
"""
612
Handles responding to interactions.
613
"""
614
615
def __init__(self, interaction: Interaction) -> None: ...
616
617
@property
618
def is_done(self) -> bool:
619
"""Whether a response has been sent."""
620
621
async def send_message(
622
self,
623
content: str = None,
624
*,
625
embed: Embed = None,
626
embeds: List[Embed] = None,
627
view: View = None,
628
tts: bool = False,
629
ephemeral: bool = False,
630
file: File = None,
631
files: List[File] = None,
632
**kwargs
633
) -> None:
634
"""Send a response message."""
635
636
async def defer(self, *, ephemeral: bool = False, invisible: bool = True) -> None:
637
"""Defer the response."""
638
639
async def edit_message(
640
self,
641
*,
642
content: str = None,
643
embed: Embed = None,
644
embeds: List[Embed] = None,
645
view: View = None,
646
file: File = None,
647
files: List[File] = None,
648
**kwargs
649
) -> None:
650
"""Edit the original message (for component interactions)."""
651
652
async def send_modal(self, modal: Modal) -> None:
653
"""Send a modal response."""
654
655
async def autocomplete(
656
self,
657
choices: List[OptionChoice]
658
) -> None:
659
"""Send autocomplete choices."""
660
661
class InteractionMessage:
662
"""
663
Represents a message sent via interaction.
664
"""
665
666
@property
667
def id(self) -> int: ...
668
@property
669
def type(self) -> MessageType: ...
670
@property
671
def author(self) -> Union[User, Member]: ...
672
@property
673
def content(self) -> str: ...
674
@property
675
def embeds(self) -> List[Embed]: ...
676
@property
677
def attachments(self) -> List[Attachment]: ...
678
@property
679
def created_at(self) -> datetime: ...
680
@property
681
def edited_at(self) -> Optional[datetime]: ...
682
@property
683
def flags(self) -> MessageFlags: ...
684
@property
685
def components(self) -> List[Component]: ...
686
687
async def edit(
688
self,
689
*,
690
content: str = None,
691
embed: Embed = None,
692
embeds: List[Embed] = None,
693
view: View = None,
694
file: File = None,
695
files: List[File] = None,
696
**kwargs
697
) -> InteractionMessage:
698
"""Edit the message."""
699
700
async def delete(self, *, delay: float = None) -> None:
701
"""Delete the message."""
702
703
class MessageInteraction:
704
"""
705
Represents the interaction that created a message.
706
"""
707
708
@property
709
def id(self) -> int: ...
710
@property
711
def type(self) -> InteractionType: ...
712
@property
713
def name(self) -> str: ...
714
@property
715
def user(self) -> Union[User, Member]: ...
716
```
717
718
### Command Permissions and Restrictions
719
720
Functions and decorators for controlling command access and behavior.
721
722
```python { .api }
723
def default_permissions(**perms) -> Callable:
724
"""
725
Set default permissions required for a command.
726
727
Parameters:
728
**perms: Permission flags (e.g., manage_messages=True)
729
"""
730
731
def guild_only() -> Callable:
732
"""Restrict command to guilds only (not DMs)."""
733
734
def is_nsfw() -> Callable:
735
"""Mark command as NSFW (age-restricted)."""
736
737
def describe(**kwargs) -> Callable:
738
"""
739
Add descriptions to command parameters.
740
741
Parameters:
742
**kwargs: Parameter descriptions (parameter_name="description")
743
"""
744
745
def checks_any(*checks) -> Callable:
746
"""
747
Require that any of the given checks pass.
748
749
Parameters:
750
*checks: Check functions to evaluate
751
"""
752
753
def has_permissions(**perms) -> Callable:
754
"""
755
Check if user has specific permissions.
756
757
Parameters:
758
**perms: Permission flags to check
759
"""
760
761
def has_role(role: Union[int, str, Role]) -> Callable:
762
"""
763
Check if user has a specific role.
764
765
Parameters:
766
- role: Role ID, name, or Role object
767
"""
768
769
def has_any_role(*roles: Union[int, str, Role]) -> Callable:
770
"""
771
Check if user has any of the specified roles.
772
773
Parameters:
774
*roles: Role IDs, names, or Role objects
775
"""
776
777
def bot_has_permissions(**perms) -> Callable:
778
"""
779
Check if bot has specific permissions.
780
781
Parameters:
782
**perms: Permission flags to check
783
"""
784
785
def is_owner() -> Callable:
786
"""Check if user is the bot owner."""
787
788
class Permissions:
789
"""Check class for permission verification."""
790
791
def __init__(self, **perms) -> None: ...
792
793
def predicate(self, ctx: ApplicationContext) -> bool:
794
"""Check if permissions are satisfied."""
795
```
796
797
### Enumerations for Commands
798
799
Command-related enumerations and constants.
800
801
```python { .api }
802
class ApplicationCommandType(Enum):
803
"""Application command types."""
804
chat_input = 1 # Slash command
805
user = 2 # User context menu
806
message = 3 # Message context menu
807
808
class SlashCommandOptionType(Enum):
809
"""Slash command option types."""
810
sub_command = 1
811
sub_command_group = 2
812
string = 3
813
integer = 4
814
boolean = 5
815
user = 6
816
channel = 7
817
role = 8
818
mentionable = 9
819
number = 10
820
attachment = 11
821
822
class InteractionType(Enum):
823
"""Interaction types."""
824
ping = 1
825
application_command = 2
826
message_component = 3
827
application_command_autocomplete = 4
828
modal_submit = 5
829
830
class InteractionResponseType(Enum):
831
"""Interaction response types."""
832
pong = 1
833
channel_message_with_source = 4
834
deferred_channel_message_with_source = 5
835
deferred_update_message = 6
836
update_message = 7
837
application_command_autocomplete_result = 8
838
modal = 9
839
840
class InteractionContextType(Enum):
841
"""Where interactions can be used."""
842
guild = 0
843
bot_dm = 1
844
private_channel = 2
845
846
class IntegrationType(Enum):
847
"""Integration types for applications."""
848
guild_install = 0
849
user_install = 1
850
```
851
852
The commands and interactions system provides comprehensive support for Discord's modern application command framework, enabling rich interactive experiences with slash commands, context menus, autocomplete, and sophisticated user interfaces.