Commands
Slash
- class discord_ui.Slash(client, parse_method=4, auto_sync=True, sync_on_cog=False, wait_sync=1, auto_defer=False)
A class for using slash commands
- client:
commands.Bot
The bot client
- parse_method:
bool
, optional How received option data should be treated; Default
ParseMethod.AUTO
- sync_on_cog:
bool
, optional Whether the slashcommands should be updated whenever a new cog is added or removed; Default
False
- wait_sync:
float
, optional How many seconds will be waited until the commands are going to be synchronized; Default
1
- auto_defer: Tuple[
bool
,bool
] Settings for the auto-defer; Default
(True, False)
[0]
: Whether interactions should be deferred automatically[1]
: Whether the deferration should be hidden (True) or public (False)
Example for using slash commands
... # Your bot declaration and everything slash = Slash(client)
For creating a slash command use
... @slash.command(name="my_command", description="this is my slash command", options=[SlashOption(str, "option", "this is an option")]) async def command(ctx: SlashInteraction): ...
And for subcommand groups use
... @slash.subcommand_group(base_names=["base", "group"], name="sub", description="this is a sub command group") async def subgroup(ctx: SubSlashInteraction): ...
- add_build(builder)
Adds a subclass of SlashBuilder to the internal cache and creates the command in the api
- builder:
SlashBuilder
The built SlashCommand you want to add
- builder:
- add_command(name=None, callback=None, description=None, options=None, guild_ids=None, default_permission=True, guild_permissions=None) Union[discord_ui.slash.types.SlashCommand, Coroutine]
Adds a new slashcommand
- name:
str
1-32 characters long name; default MISSING
Note
The name will be corrected automaticaly (spaces will be replaced with “-” and the name will be lowercased)
- callback:
function
, optional A callback that will be called when the command was received
- description:
str
, optional 1-100 character description of the command; default the command name
- options: List[
SlashOptions
], optional The parameters for the command; default MISSING
- choices: List[
tuple
] | List[dict
], optional Choices for string and int types for the user to pick from; default MISSING
- guild_ids: List[
str
|int
], optional A list of guild ids where the command is available; default MISSING
- default_permission:
bool
|discord.Permissions
, optional - Permissions that a user needs to have in order to execute the command, default
True
. If a bool was passed, it will indicate whether all users can use the command (
True
) or not (False
)
- Permissions that a user needs to have in order to execute the command, default
- guild_permissions: Dict[
guild_id
:SlashPermission
] - The permissions for the command in guilds
Format:
{"guild_id": SlashPermission}
ClientException
Commands should be synced but the client is not ready yet
- name:
- command(name=None, description=None, options=None, guild_ids=None, default_permission=True, guild_permissions=None) Callable[[...], discord_ui.slash.types.SlashCommand]
A decorator for a slash command
- command in discord:
/name [options]
- name:
str
, optional 1-32 characters long name; default MISSING
Note
The name will be corrected automaticaly (spaces will be replaced with “-” and the name will be lowercased)
- description:
str
, optional 1-100 character description of the command; default the command name
- options: List[
SlashOptions
], optional The parameters for the command; default MISSING
- choices: List[
tuple
] | List[dict
], optional Choices for string and int types for the user to pick from; default MISSING
- guild_ids: List[
str
|int
], optional A list of guild ids where the command is available; default MISSING
- default_permission:
bool
|discord.Permissions
, optional - Permissions that a user needs to have in order to execute the command, default
True
. If a bool was passed, it will indicate whether all users can use the command (
True
) or not (False
)
- Permissions that a user needs to have in order to execute the command, default
- guild_permissions: Dict[
guild_id
:SlashPermission
] - The permissions for the command in guilds
Format:
{"guild_id": SlashPermission}
- callback:
method(ctx)
- The asynchron function that will be called if the command was used
- ctx:
SlashInteraction
The used slash command
Note
ctx
is just an example name, you can use whatever you want for that- ctx:
@slash.command(name="hello_world", description="This is a test command", options=[ SlashOption(str, name="parameter", description="this is a parameter", choices=[("choice 1", "test")]) ], guild_ids=[785567635802816595], default_permission=False, guild_permissions={ 785567635802816595: SlashPermission(allowed={"539459006847254542": SlashPermission.USER}) } ) async def command(ctx, parameter = None): ...
- message_command(name=None, guild_ids=None, default_permission=True, guild_permissions=None)
- Decorator for message context commands in discord.
Right-click message
->apps
->commands is displayed here
- name:
str
, optional The name of the command; default MISSING
- guild_ids: List[
str
|int
] A list of guilds where the command can be used
- default_permission:
bool
|discord.Permissions
, optional - Permissions that a user needs to have in order to execute the command, default
True
. If a bool was passed, it will indicate whether all users can use the command (
True
) or not (False
)
- Permissions that a user needs to have in order to execute the command, default
- guild_permissions: Dict[
SlashPermission
], optional Special permissions for guilds; default MISSING
- callback:
method(ctx, message)
- The asynchron function that will be called if the command was used
- ctx:
SubSlashInteraction
The used slash command
- message:
Message
The message on which the command was used
Note
ctx
andmessage
are just example names, you can use whatever you want for that- ctx:
@slash.message_command(name="quote", guild_ids=[785567635802816595], default_permission=False, guild_permissions={ 785567635802816595: SlashPermission(allowed={ "585567635802816595": SlashPermission.USER }) }) async def quote(ctx, message): ...
- subcommand(base_names, name=None, description=None, options=None, guild_ids=None, default_permission=True, guild_permissions=None)
A decorator for a subcommand group
- command in discord
/base_names... name [options]
- base_names: List[
str
] |str
- The names of the parent bases, currently limited to 2
If you want to make a subcommand (
/base name
), you have to use a str instead of a list
- name:
str
, optional 1-32 characters long name; default MISSING
Note
The name will be corrected automaticaly (spaces will be replaced with “-” and the name will be lowercased)
- description:
str
, optional 1-100 character description of the command; default the command name
- options: List[
SlashOptions
], optional The parameters for the command; default MISSING
- choices: List[
tuple
] | List[dict
], optional Choices for string and int types for the user to pick from; default MISSING
- guild_ids: List[
str
|int
], optional A list of guild ids where the command is available; default MISSING
- default_permission:
bool
|discord.Permissions
, optional - Permissions that a user needs to have in order to execute the command, default
True
. If a bool was passed, it will indicate whether all users can use the command (
True
) or not (False
)
- Permissions that a user needs to have in order to execute the command, default
- guild_permissions: Dict[
guild_id
:SlashPermission
] - The permissions for the command in guilds
Format:
{"guild_id": SlashPermission}
Note
Permissions will be the same for every subcommand with the same base
- callback:
method(ctx)
- The asynchron function that will be called if the command was used
- ctx:
SubSlashInteraction
The used slash command
Note
ctx
is just an example name, you can use whatever you want for that- ctx:
subcommand
@slash.subcommand_group(base_names="hello", name="world", options=[ SlashOption(type="user", name="user", description="the user to tell the holy words") ], guild_ids=[785567635802816595]) async def command(ctx, user): ...
subcommand-group
@slash.subcommand_group(base_names=["hello", "beautiful"], name="world", options=[ SlashOption(type="user", name="user", description="the user to tell the holy words") ], guild_ids=[785567635802816595]) async def command(ctx, user): ...
- sync_commands()
deprecated, use
commands.sync
instead
- user_command(name=None, guild_ids=None, default_permission=True, guild_permissions=None)
- Decorator for user context commands in discord.
Right-click username
->apps
->commands is displayed here
- name:
str
, optional The name of the command; default MISSING
- guild_ids: List[
str
|int
] A list of guilds where the command can be used
- default_permission:
bool
|discord.Permissions
, optional - Permissions that a user needs to have in order to execute the command, default
True
. If a bool was passed, it will indicate whether all users can use the command (
True
) or not (False
)
- Permissions that a user needs to have in order to execute the command, default
- guild_permissions: Dict[
SlashPermission
], optional Special permissions for guilds; default MISSING
- callback:
method(ctx, user)
- The asynchron function that will be called if the command was used
- ctx:
SubSlashInteraction
The used slash command
- user:
discord.Member
The user on which the command was used
Note
ctx
anduser
are just example names, you can use whatever you want for that- ctx:
@slash.user_command(name="call", guild_ids=[785567635802816595], default_permission=False, guild_permissions={ 785567635802816595: SlashPermission(allowed={ "585567635802816595": SlashPermission.USER }) }) async def call(ctx, message): ...
- client:
import discord
from discord.ext import commands
from discord_ui import Slash
client = commands.Bot(" ")
slash = Slash(client)
Events
We got 2 events to listen for your client
slash_command
This event will be dispatched whenever a normal slash command was used
One parameter will be passed
SlashInteraction
|SlashedSubCommand
@client.listen('on_slash_command')
def slash_command(ctx: SlashInteraction):
...
await client.wait_for('slash_command', check=lambda ctx: ...)
context_command
This event will be dispatched whenever a context command was used
Two parameters will be passed
Message
|discord.User
@client.listen('context_command')
def on_context(ctx: ContextInteraction, param):
...
await client.wait_for('context_command', check=lambda ctx, param: ...)
SlashOption
- class discord_ui.SlashOption(type, name, description=None, required=False, choices=None, autocomplete=None, choice_generator=None, options=None, channel_types=None, min_value=None, max_value=None)
An option for a slash command
- type:
int
|str
|class
|OptionType
What type of parameter the option should accept.
- name:
str
1-32 lowercase character name for the option.
- description:
str
, optional 1-100 character description of the command; default
- required:
bool
, optional If the parameter is required or optional; default False
- choices: List[
dict
], optional - Choices for string and int types for the user to pick from; default None
Choices should be formated like this:
[{"name": "name of the choice", "value": "the real value"}, ...]
Note
The choice value has to be of the same type as the type this option accepts.
- autocomplete:
bool
, optional Whether the choices should be autogenerated; default None
- choice_generator:
function
, optional - A function that generates the choices for this option. Needds to return a list of dicts or tuples; default None
This will automatically set autocomplete to True if autocomplete was not passed.
- options: List[
SlashOption
] This parameter is only for subcommands to work, you shouldn’t need to use that, unless you know what you’re doing.
- channel_types: List[
discord.ChannelType
] If the option is a channel type, the channels shown will be restricted to these types.
- min_value:
int
If the option type is numeric (
float
orint
) the minimum value permitted- max_value:
int
If the option type is numeric (
float
orint
) the maximum value permitted
- property autocomplete: bool
Whether the choices for this option should be autocompleted
- autocomplete_function(callback)
Decorator for the autocomplete choice generator
op = SlashOption(...) @op.autocomplete_function async def generator(ctx): ...
- property channel_types
A list of channel types that will restrict the shown channels for this option
- choice_generator: Callable[[Any], List[Union[dict, tuple]]]
A function which will generate choices for this option
- property choices: List[dict]
Choices for string and int types for the user to pick from
Note
Choices are formated like this:
[{"name": "name of the choice", "value": "the real value"}, ...]
- property description: str
The description of the option appearing under the name
- property focused: bool
“Whether this option was focused while autocomplete
- property max_value
If the option is an
INTEGER
orNUMBER
type, the maximum value permitted
- property min_value
If the option is an
INTEGER
orNUMBER
type, the minimum value permitted
- property name: str
The name of the option appearing in discord
- property options: discord_ui.slash.types.SlashOptionCollection
The parameters for the command. You can use the option’s name (
.options["option name"]
) or the index of the option (.options[index]
) to get an element.
- property required: bool
Whether this parameter is required to use or not
- property type: int
Parameter type that the option accepts
- type:
SlashPermission
- class discord_ui.SlashPermission(allowed: Optional[Union[dict, list]] = None, forbidden: Optional[Union[dict, list]] = None)
Permissions for a slash commannd
- allowed:
dict
| List[discord.Member
|discord.User
|discord.Role
], optional - A list of ids, users or members that can use the command; default None
Format:
{"role_or_user_id": permission_type}]
- forbidden:
dict
| List[discord.Member
|discord.User
|discord.Role
], optional A list of ids, users or members that are forbidden to use the command; default None
Note
If you want to use a role id, the permission type has to be 1, and if you want to specify a user id, it has to be 2
You can use
SlashPermission.Role
andSlashPermission.User
instead- Role = 1
Permission type for a role
- User = 2
Permission type for a user
- allowed:
SlashInteraction
- class discord_ui.SlashInteraction
An interaction created by a
SlashCommand
- args: Dict[str, Union[str, int, bool, discord.member.Member, discord.channel.TextChannel, discord.role.Role, float]]
The options that were received
- author: Union[discord.member.Member, discord.user.User]
The user who used the command
- property channel: Union[discord.abc.GuildChannel, discord.abc.PrivateChannel]
The channel where the interaction was created
- command: discord_ui.slash.types.SlashCommand
The original command instance that was used. If you change things here, the changes will be applied globally
- property created_at
The interaction’s creation time in UTC
- async defer(hidden=False)
This will acknowledge the interaction. This will show the (Bot is thinking…) Dialog
Note
This function should be used if the bot needs more than 15 seconds to respond
- hidden:
bool
, optional Whether the loading thing should be only visible to the user; default False.
- hidden:
- property guild: discord.guild.Guild
The guild where the interaction was created
- permissions: discord_ui.slash.types.SlashPermission
The permissions for this guild
- async respond(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, nonce=None, allowed_mentions=None, mention_author=None, components=None, delete_after=None, listener=None, hidden=False, ninja_mode=False) Union[Message, EphemeralMessage]
Responds to the interaction
- content:
str
, optional The raw message content
- tts:
bool
Whether the message should be send with text-to-speech
- embed:
discord.Embed
Embed rich content
- embeds: List[
discord.Embed
] A list of embeds for the message
- file:
discord.File
The file which will be attached to the message
- files: List[
discord.File
] A list of files which will be attached to the message
- nonce:
int
The nonce to use for sending this message
- allowed_mentions:
discord.AllowedMentions
Controls the mentions being processed in this message
- mention_author:
bool
Whether the author should be mentioned
- components: List[
Button
|LinkButton
|SelectMenu
] A list of message components to be included
- delete_after:
float
After how many seconds the message should be deleted, only works for non-hiddend messages; default MISSING
- listener:
Listener
A component-listener for this message
- hidden:
bool
Whether the response should be visible only to the user
- ninja_mode:
bool
If true, the client will respond to the button interaction with almost nothing and returns nothing
Message
|EphemeralMessage
Returns the sent message
- content:
- async send(content=None, *, tts=None, embed=None, embeds=None, file=None, files=None, nonce=None, allowed_mentions=None, mention_author=None, components=None, delete_after=None, listener=None, hidden=False, force=False) Union[discord_ui.receive.Message, discord_ui.receive.EphemeralMessage]
Sends a message to the interaction using a webhook
- content:
str
, optional The raw message content
- tts:
bool
, optional Whether the message should be send with text-to-speech
- embed:
discord.Embed
, optional Embed rich content
- embeds: List[
discord.Embed
], optional A list of embeds for the message
- file:
discord.File
, optional The file which will be attached to the message
- files: List[
discord.File
], optional A list of files which will be attached to the message
- nonce:
int
, optional The nonce to use for sending this message
- allowed_mentions:
discord.AllowedMentions
, optional Controls the mentions being processed in this message
- mention_author:
bool
, optional Whether the author should be mentioned
- components: List[
Button
|LinkButton
|SelectMenu
] A list of message components to be included
- delete_after:
float
, optional After how many seconds the message should be deleted, only works for non-hiddend messages; default MISSING
- listener:
Listener
, optional A component-listener for this message
- hidden:
bool
, optional Whether the response should be visible only to the user
- ninja_mode:
bool
, optional If true, the client will respond to the button interaction with almost nothing and returns nothing
- force:
bool
, optional Whether sending the follow-up message should be forced. If
False
, then a follow-up message will only be send if.responded
is True; default False
Message
|EphemeralMessage
Returns the sent message
- content:
Ephemeral
EphemeralMessage
- class discord_ui.EphemeralMessage
Represents a hidden (ephemeral) message
- async delete()
Override for delete function that will throw an exception
- async edit(*args, **fields)
Edits the message and updates its properties
Note
If a paremeter is None, the attribute will be removed from the message
- content:
str
The new message content
- embed:
discord.Embed
The new embed of the message
- embeds: List[
discord.Embed
] The new list of discord embeds
- attachments: List[
discord.Attachment
] A list of new attachments
- supress:
bool
Whether the embeds should be shown
- delete_after:
float
After how many seconds the message should be deleted
- allowed_mentions:
discord.AllowedMentions
The mentions proceeded in the message
- components: List[
Button
|LinkButton
|SelectMenu
] A list of components to be included the message
- content:
EphemeralResponseMessage
- class discord_ui.EphemeralResponseMessage
A ephemeral message which was created from an interaction
Important
Methods like .edit(), which change the original message, need a token paremeter passed in order to work
- async delete()
Override for delete function that will throw an exception
- async disable_components(token, disable=True, **fields)
Disables all component in the message
- disable:
bool
, optional Whether to disable (
True
) or enable (False
) all components; default True
- disable:
- async edit(token, *args, **fields)
Edits the message
- token:
str
The token of the interaction with wich this ephemeral message was sent
- fields:
kwargs
The fields to edit (ex. content=”…”, embed=…, attachments=[…])
Example
async def testing(ctx): msg = await ctx.send("hello hidden world", components=[Button("test")]) btn = await msg.wait_for("button", client) await btn.message.edit(ctx.token, content="edited", components=None)
- token:
Tools
- discord_ui.create_choice(name, value) dict
A function that will create a choice for a
SlashOption
- name:
str
The name of the choice
- value:
Any
The value that will be received when the user selected this choice
dict
The created choice
- name: