Overview
Slash commands are the primary way users interact with Discord bots. JDA provides a comprehensive API for creating, registering, and handling slash commands.
Creating Slash Commands
Commands.slash()
Create a slash command builder with a name and description.
The command name, 1-32 lowercase alphanumeric characters (with dash)
The command description, 1-100 characters
SlashCommandData slash(@Nonnull String name, @Nonnull String description)
Example: Basic Command
SlashBotExample.java:55-69
commands.addCommands(Commands.slash("ban", "Ban a user from this server. Requires permission to ban users.")
// USER type allows to include members of the server or other users by id
.addOptions(new OptionData(USER, "user", "The user to ban")
// This must be filled out by the command user
.setRequired(true))
// This is optional by default and does not need to be provided
.addOptions(new OptionData(INTEGER, "del_days", "Delete messages from the past days.")
// Only allow values between 0 and 7 (inclusive)
.setRequiredRange(0, 7))
// optional reason
.addOptions(new OptionData(STRING, "reason", "The ban reason to use (default: Banned by <user>)"))
// This way the command can only be executed from a guild, and not the DMs
.setContexts(InteractionContextType.GUILD)
// Only members with the BAN_MEMBERS permission are going to see this command
.setDefaultPermissions(DefaultMemberPermissions.enabledFor(Permission.BAN_MEMBERS)));
Adding Options
addOption()
Add an option to the command.
The type of option (STRING, INTEGER, BOOLEAN, USER, CHANNEL, ROLE, MENTIONABLE, NUMBER, ATTACHMENT)
The lowercase option name, 1-32 characters
The option description, 1-100 characters
Whether this option is required
SlashCommandData.java:408-410
default SlashCommandData addOption(
@Nonnull OptionType type, @Nonnull String name, @Nonnull String description, boolean required)
addOptions()
Add multiple option data objects.
The OptionData objects to add (max 25 options)
SlashCommandData.java:310
SlashCommandData addOptions(@Nonnull OptionData... options)
Example: Command with Options
SlashBotExample.java:72-78
commands.addCommands(Commands.slash("say", "Makes the bot say what you tell it to")
// Allow the command to be used anywhere (Bot DMs, Guild, Friend DMs, Group DMs)
.setContexts(InteractionContextType.ALL)
// Allow the command to be installed anywhere (Guilds, Users)
.setIntegrationTypes(IntegrationType.ALL)
// you can add required options like this too
.addOption(STRING, "content", "What the bot should say", true));
Option Configuration
OptionData Constructor
Create an option with detailed configuration.
The option name, 1-32 alphanumeric (with dash) lowercase characters
The option description, 1-100 characters
Whether this option is required
public OptionData(
@Nonnull OptionType type, @Nonnull String name, @Nonnull String description, boolean isRequired)
setRequiredRange()
Set min and max value constraints for INTEGER or NUMBER options.
The minimum value (must be greater than or equal to -2^53 + 1)
The maximum value (must be less than or equal to 2^53 - 1)
public OptionData setRequiredRange(long minValue, long maxValue)
addChoice()
Add predefined choices to STRING, INTEGER, or NUMBER options.
The choice name shown to users (max 100 characters)
value
String/long/double
required
The value received when this choice is selected
public OptionData addChoice(@Nonnull String name, @Nonnull String value)
Handling Slash Commands
onSlashCommandInteraction()
Listen for slash command interactions.
SlashBotExample.java:102-130
@Override
public void onSlashCommandInteraction(SlashCommandInteractionEvent event) {
// Only accept commands from guilds
if (event.getGuild() == null) {
return;
}
switch (event.getName()) {
case "ban":
// the "user" option is required, so it doesn't need a null-check here
Member member = event.getOption("user").getAsMember();
User user = event.getOption("user").getAsUser();
ban(event, user, member);
break;
case "say":
// content is required so no null-check here
say(event, event.getOption("content").getAsString());
break;
case "leave":
leave(event);
break;
case "prune":
// 2 stage command with a button prompt
prune(event);
break;
default:
event.reply("I can't handle that command right now :(")
.setEphemeral(true)
.queue();
}
}
Getting Option Values
SlashBotExample.java:193-205
// optional command argument, fall back to 0 if not provided
int delDays = event.getOption(
"del_days",
0,
// this last part is a method reference used to "resolve" the option value
OptionMapping::getAsInt);
// optional ban reason with a lazy evaluated fallback (supplier)
String reason = event.getOption(
"reason",
// used if getOption("reason") is null (not provided)
() -> "Banned by " + event.getUser().getName(),
// used if getOption("reason") is not null (provided)
OptionMapping::getAsString);
Command Configuration
setContexts()
Restrict where the command can be used.
contexts
InteractionContextType...
required
The contexts where this command is available (GUILD, BOT_DM, PRIVATE_CHANNEL)
SlashCommandData.java:69-70
default SlashCommandData setContexts(@Nonnull InteractionContextType... contexts)
setDefaultPermissions()
Set which permissions users need to see and use this command.
permission
DefaultMemberPermissions
required
The default permissions required
SlashCommandData setDefaultPermissions(@Nonnull DefaultMemberPermissions permission)
setIntegrationTypes()
Set where the command can be installed.
integrationTypes
IntegrationType...
required
The integration types (GUILD_INSTALL, USER_INSTALL)
SlashCommandData.java:79-80
default SlashCommandData setIntegrationTypes(@Nonnull IntegrationType... integrationTypes)
Subcommands
addSubcommands()
Add subcommands to create command groups.
subcommands
SubcommandData...
required
The subcommands to add (max 25)
SlashCommandData.java:478
SlashCommandData addSubcommands(@Nonnull SubcommandData... subcommands)
Commands with subcommands cannot have options. You must choose between options or subcommands/subcommand groups.
Registering Commands
Global Commands
SlashBotExample.java:52-98
CommandListUpdateAction commands = jda.updateCommands();
commands.addCommands(
Commands.slash("ban", "Ban a user from this server")
.addOptions(new OptionData(USER, "user", "The user to ban").setRequired(true))
);
// Send commands to Discord
commands.queue();
Guild Commands
Guild guild = jda.getGuildById("123456789");
guild.updateCommands()
.addCommands(Commands.slash("admin", "Admin only command"))
.queue();
Constants
Commands.MAX_SLASH_COMMANDS - Maximum of 100 global or guild slash commands
OptionData.MAX_NAME_LENGTH - 32 characters for option names
OptionData.MAX_DESCRIPTION_LENGTH - 100 characters for option descriptions
OptionData.MAX_CHOICES - 25 choices per option
CommandData.MAX_OPTIONS - 25 options per command