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

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

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

@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

@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