Skip to main content

Interactions

The InteractionHub holds all your commands. It deploys them to Discord, receives the interactions and calls your handlers.

Create the hub​

InteractionHub<Slash, Message, User> hub = InteractionHub.builder(shardManager)
.withLocalizer(localizer)
.withCommands(new Ping(), new Settings())
.withMessages(new ReportMessage())
.withUsers(new UserInfo())
.withDefaultPagination()
.withDefaultMenuService()
.withDefaultModalService()
.build();

build() checks every command, then deploys them in the background and registers the hub as a JDA listener. A command that cannot be built fails build() with an IllegalStateException that names the command.

MethodWhat it does
withLocalizer(ILocalizer)Localizes command names, descriptions and replies. See localization.
withCommands(...)Adds slash commands. Takes Slash objects or SlashProviders.
withMessages(...)Adds message context commands. Takes Message objects or MessageProviders.
withUsers(...)Adds user context commands. Takes User objects or UserProviders.
withDefaultPagination(), withPagination(...)Enables pagination.
withDefaultMenuService(), withMenuService(...)Enables menus.
withDefaultModalService(), withModalService(...)Enables modals.
withConversationSystem()Enables conversations.
withGuildCommandMapper(...)Decides on which guilds a private command is deployed.
withCommandAliases(...)Gives a slash command another name on single guilds.
withCommandErrorHandler(...)Called when a handler throws. The default logs the error.
withPostCommandHook(...)Called after every command, failed or not.
withEntitlementProvider(...), withSKUConfiguration(...), withPremiumErrorMessage(...)Premium checks.
testMode(), cleanGuildCommands()Deployment switches, see below.

Slash commands​

A slash command starts with Slash.of(name, description). The builder asks for the settings first, then either one handler or a set of sub commands.

public class Ping extends SlashCommand {
public Ping() {
super(Slash.of("ping", "command.ping.description")
.guildOnly()
.command(new PingHandler()));
}
}

With sub commands and arguments:

public class Log extends SlashCommand {
public Log() {
super(Slash.of("log", "command.log.description")
.guildOnly()
.withPermission(Permission.MESSAGE_MANAGE)
.subCommand(SubCommand.of("received", "command.log.received.description")
.handler(new Received())
.argument(Argument.user("user", "command.log.received.options.user.description")
.asRequired()))
.subCommand(SubCommand.of("donated", "command.log.donated.description")
.handler(new Donated())));
}
}

Groups bundle sub commands one level deeper: .group(Group.of("name", "description").subCommand(...)).

Settings​

MethodEffect
guildOnly()Only usable in guilds. By default a command also works in DMs with the bot.
withPermission(Permission, Permission...)The default member permissions a user needs to see the command.
adminCommand()Hidden for everyone except administrators by default.
publicCommand()Visible for everyone. This is the default.
privateCommand()Only deployed on the guilds the guild command mapper returns.
globalCommand()Deployed globally. This is the default.
skus(...)Requires one of these SKUs, see premium.
unlocalized()Uses the name and description as written, without looking them up.

Permissions only set Discord's default member permissions. Server admins can change them, and cjda-util does not check them again when the command runs.

Arguments​

FactoryOption typeExtra methods
Argument.text(name, description)StringminLength, maxLength, withAutoComplete
Argument.integer(name, description)Integermin, max, withAutoComplete
Argument.number(name, description)Numbermin, max, withAutoComplete
Argument.bool(name, description)Boolean
Argument.user, role, channel, mentionable, attachmentas named

Every argument has asRequired().

Handlers​

A handler implements SlashHandler:

public class Received implements SlashHandler {
@Override
public void onSlashCommand(SlashCommandInteractionEvent event, EventContext context) {
Member member = event.getOption("user").getAsMember();
event.reply(context.localize("command.log.received.message", Replacement.createMention(member)))
.setEphemeral(true)
.queue();
}

@Override
public void onAutoComplete(CommandAutoCompleteInteractionEvent event, EventContext context) {
event.replyChoices(Completion.complete(event.getFocusedOption().getValue(), "one", "two")).queue();
}
}

onAutoComplete is optional. It is called for arguments marked with withAutoComplete().

The EventContext gives you the services of the hub:

MethodReturns
localize(key, Replacement...)The text in the guild's language, or the user's language in DMs.
guildLocalizer(), userLocalizer()A LocalizationContext for the guild or the user.
registerPage(...)Sends a paginated message.
registerMenu(...)Sends a menu.
registerModal(...)Opens a modal.
startDialog(...)Starts a conversation.
entitlements()The SKUs of the user or guild, see premium.
interactionHub()The hub itself.

During autocomplete there is no reply callback. Only reply with choices there.

Message and user commands​

Context commands appear when someone right-clicks a message or a user.

public class ReportMessage implements MessageProvider<Message> {
@Override
public Message message() {
return Message.of("Report Message")
.handler((event, context) -> event.reply("Reported.").setEphemeral(true).queue())
.setContext(Set.of(InteractionContextType.GUILD))
.withPermission(Permission.MESSAGE_MANAGE)
.build();
}
}

User.of(name) works the same way with a UserHandler and UserProvider<User>.

Localized names​

By default every name and description is a locale key. cjda-util looks up:

CommandKeys
Slash commandcommand.<command>.name, command.<command>.description
Sub commandcommand.<command>.<sub>.name, command.<command>.<sub>.description
Groupcommand.<command>.<group>.name, command.<command>.<group>.description
Sub command in a groupcommand.<command>.<group>.<sub>.name, command.<command>.<group>.<sub>.description
Argument of a commandcommand.<command>.options.<argument>.name and .description
Argument of a sub commandcommand.<command>.<sub>.options.<argument>.name and .description
Argument in a groupcommand.<command>.<group>.<sub>.options.<argument>.name and .description
Message commandmessage.<name in snake case>.name
User commanduser.<name in snake case>.name

Missing or invalid keys are logged as warnings when the hub starts. Names must be lower snake case and at most 32 characters long.

Deployment​

Commands are deployed on a background thread once all shards are ready. hub.deployment() returns a future that completes when the deployment is done.

  • Global commands are deployed globally.
  • Private commands are deployed on the guilds the guild command mapper returns for them.
  • Aliases from withCommandAliases deploy a slash command under another name on a guild. The command still runs as the original command.
  • When the bot joins a guild, its guild commands are deployed. Call hub.refreshGuildCommands(guild) after you change what the mapper or the alias function returns.

For development there are two switches. Both can be set in the builder, as a system property or as an environment variable:

BuilderPropertyEnvironmentEffect
testMode()cjda.interactions.testmodeCJDA_INTERACTIONS_TESTMODEDeploys global commands as guild commands on every guild, so changes show up at once, and removes the global commands.
cleanGuildCommands()cjda.interactions.cleanguildcommandsCJDA_INTERACTIONS_CLEANGUILDCOMMANDSRedeploys the guild commands on every guild the bot is in, which removes stale ones.

The environment variable wins over the system property, and a builder call wins over both.

Errors​

When a handler throws, the hub calls the command error handler and the post command hook with an InteractionResult. Use the hook for metrics and for error replies:

.withPostCommandHook(result -> {
metrics.log(result.context().interaction().meta().name());
if (result.failed()) {
log.error("Command {} failed", result.commandAsString(), result.exception());
}
})

To catch exceptions from your other JDA listeners as well, use the InterceptingEventManager:

DefaultShardManagerBuilder.createDefault(token)
.setEventManagerProvider(id -> new InterceptingEventManager((event, error) -> log.error("Listener failed", error)));