Getting Started — discord-py-slash-command documentation (2024)

The basics.¶

First, let’s explain by how commands are parsed through the Discord Bot API.

As you may know, Discord relies a lot on the interaction of HTTP Requests andJSON tables. As is with the case here, commands are the exact same way withhaving JSON tables to structure the design of it for Discord to understand. Wecan apply this information likewise with how slash commands are to be designedin the Python code. Below attached is from the Discord Developer Portal on SlashCommands for showing how they are designed.

This table shows us the way that Discord handles the structure of commands forslash commands through their Bot API. For visualization purposes, we’ll quicklymake a JSON example (although we won’t be using it) in order to explain how thisworks:

{ "name": "test", "description": "This is just a test command, nothing more.",}

Now that we have a basic understanding of how the JSON table works, we cantake this knowledge and convert it into a decorator method for the Pythoncode as shown below:

@slash.slash(name="test", description="This is just a test command, nothing more.")async def test(ctx): await ctx.send(content="Hello World!")

Now that we’ve gone over how Discord handles the declaration of slash commandsthrough their Bot API, let’s go over what some of the other things mean withinthe logical part of our code, the command function:

Giving some options for variety.¶

The next thing that we will begin to talk about is the implementation of options,otherwise well-known as “arguments” in discord.py commands.

The JSON structure of options are designed up to be similar to the same premiseof how a slash command is declared. Below is the given table of how an optionJSON would appear as:

Now we have an idea of how options are declared. With this in mind, let’s quickly make a JSONexample in order to visualize this concept even further:

{ "name": "test", "description": "This is just a test command, nothing more.", "options": [ { "name": "optone", "description": "This is the first option we have.", "type": 3, "required": "false" } ]}

While the table in the basics mentions an array in particular called ApplicationCommandOptionType,there isn’t that much of an explanation on how this works. Let’s put this into better laymenterms on what this means with a table below showing all of these values:

The purpose of having the ApplicationCommandOptionType value passed into our option JSON structureis so that we can help the Discord UI understand what kind of value we’re inputting here. For instance,if we’re wanting to put in a string response, we’ll pass the ID 3 so that the UI of Discord chat barknows to format it visually this way. If we’re looking for a user, then we’ll pass ID 6 so that it presentsus with a list of users in our server instead, making it easier on our lives.

This is not to be confused, however, with formatting the response type itself. This is merely a method sothat the API wrapper can help us with passing the correct type or instance variable with the arguments of thecommand function’s code.

Now, we can finally visualize this by coding an example of this being used in the Python code shown below.

from discord_slash.utils.manage_commands import create_option@slash.slash(name="test", description="This is just a test command, nothing more.", options=[ create_option( name="optone", description="This is the first option we have.", option_type=3, required=False ) ])async def test(ctx, optone: str): await ctx.send(content=f"I got you, you said {optone}!")

Additionally, we could also declare the type of our command’s option through this method shown here:

from discord_slash.model import SlashCommandOptionType(...) option_type=SlashCommandOptionType.STRING

More in the option? Give them a choice.¶

Alas, there is also a way to give even more information to options with Discord’s Slash Commands:a choice. Not like something that you’re given at birth of when you become of legal age as an adult,we’re not here to give you that kind of life advice, but the choice of what value you want youroption to rather pass. Below is a table that shows the JSON structure of how choices are representedfor an option:

This time, only 2 fields are able to be passed for this. Below is a JSON example of how this wouldbe designed:

{ "name": "ChoiceOne", "value": "Hello command, this is my value!"}

To make it really simple, the name field is only to be used for how you want the choice to be presentedthrough Discord’s UI. It’s the “appearance” of how you want your choice shown, not the actual returned valueof it. Hence, this is why value is the second field passed for that, which can be either in the form ofa string or integer. Below is an implementation of this design in the Python code:

from discord_slash.utils.manage_commands import create_option, create_choice@slash.slash(name="test", description="This is just a test command, nothing more.", options=[ create_option( name="optone", description="This is the first option we have.", option_type=3, required=False, choices=[ create_choice( name="ChoiceOne", value="DOGE!" ), create_choice( name="ChoiceTwo", value="NO DOGE" ) ] ) ])async def test(ctx, optone: str): await ctx.send(content=f"Wow, you actually chose {optone}? :(")

Want to restrict access? Setup permissions!¶

Slash commands also supports ability to set permissions to allow only certain roles and/or usersto run a slash command. Permissions can be applied to both global and guild based commands. Theyare defined per guild ,per top-level command (the base command for subcommands), and each guild can have multiple permissions. Here table that shows the JSONstructure of how permissions are represented:

How the type parameter works is very simple. Discord has many ids to represent different things. As you canset permissions to apply for User or Role, ApplicationCommandPermissionType is used. It’s a number andfollowing table shows the supported id types for permissions:

This is an example of how a single permission will look when represented as a json object:

{ "id": 12345678, "type": 1, "permission": True}

Now, let take a look at an example. The slash command decorator have a permissions parameter whereit takes in a dictionary. The key being the guild id to apply permissions on, and value being the listof permissions to apply. For each permission, we can use the handy create_permission method tobuild the permission json explain above.

In this case, we are setting 2 permissions for guild with id of 12345678. Firstly, we are allowingrole with id 99999999 and disallowing user with id 88888888 from running the slash command.

from discord_slash.utils.manage_commands import create_permissionfrom discord_slash.model import SlashCommandPermissionType@slash.slash(name="test", description="This is just a test command, nothing more.", permissions={ 12345678: [ create_permission(99999999, SlashCommandPermissionType.ROLE, True), create_permission(88888888, SlashCommandPermissionType.USER, False) ] })async def test(ctx): await ctx.send(content="Hello World!")

Alternatively, you can use the @slash.permission decorator to define your guild permissions for thecommand as show in the following example:

from discord_slash.utils.manage_commands import create_permissionfrom discord_slash.model import SlashCommandPermissionType@slash.slash(name="test", description="This is just a test command, nothing more.")@slash.permission(guild_id=12345678, permissions=[ create_permission(99999999, SlashCommandPermissionType.ROLE, True), create_permission(88888888, SlashCommandPermissionType.USER, False) ])async def test(ctx): await ctx.send(content="Hello World!")