Commands

Slash

class discord_ui.Slash(client, parse_method=4, auto_sync=True, delete_unused=False, 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

delete_unused: bool, optional

Whether the commands that are not registered by this slash extension should be deleted in the api; Default False

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

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)

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

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)

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

@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)

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 and message are just example names, you can use whatever you want for that

@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)

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

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(delete_unused=False): 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)

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 and user are just example names, you can use whatever you want for that

@slash.user_command(name="call", guild_ids=[785567635802816595], default_permission=False, guild_permissions={
    785567635802816595: SlashPermission(allowed={
        "585567635802816595": SlashPermission.USER
    })
})
async def call(ctx, message):
    ...

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

ContextInteraction
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 or int) the minimum value permitted

max_value: int

If the option type is numeric (float or int) 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 or NUMBER type, the maximum value permitted

property min_value: If the option is an INTEGER or NUMBER 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

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 and SlashPermission.User instead

Role = 1: Permission type for a role

User = 2: Permission type for a user

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.

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

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

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

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

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)

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

Commands

Slash

Events

slash_command

context_command

SlashOption

SlashPermission

SlashInteraction

Ephemeral

EphemeralMessage

EphemeralResponseMessage

Tools

`slash_command`

`context_command`