Skip to main content

Interactions

Interaction Hierarchy

Discord sends a single event over the gateway for all interactions. Discord4J breaks this down into separate event classes allowing a better development experience for handling the interactions you care about. We use the following hierarchy to accomplish this.

Application Commands

note

For information on how to use application commands, see How-to Guides - Application Commands.

Application commands encompass several types of interactions:

  • A chat input command (formerly "slash command"), which allows users to type a command in the chat box.
  • Message command, which allows right-clicking on a message and using a context menu interaction (ex. "star message").
  • Or User command, which allows right-clicking on a user and using a context menu interaction (ex. "temp mute").

In order for guilds to use application commands your bot has created, it is required that the bot be invited with the applications.commands scope in addition to the bot scope.

Application commands can be registered globally (accessible to all guilds that your bot is invited to), or per-guild; allowing each guild to have their own unique commands as they see fit.

Chat Input (Slash Commands)

Options

Chat input commands can have options. These are just like arguments in a method, but for discord commands.

Option Types

Discord provides several built in types for options that define how each of them behave and their data type.

NameValueNote
SUB_COMMAND1
SUB_COMMAND_GROUP2Transparent to the user; a way to organize your commands in code
STRING3
INTEGER4Any integer between -2^53 and 2^53
BOOLEAN5
USER6
CHANNEL7Includes all channel types + categories
ROLE8
MENTIONABLE9Includes all users/roles
NUMBER10Any floating point number between -2^53 and 2^53
ATTACHMENT11File attachment

Choices

Choices can be defined on the STRING, INTEGER, and NUMBER option types. choices are preset values the user can pick when selecting the option that contains them.

caution

If you specify choices for an option, these are the only valid values a user may pick.

Message Commands

Message commands are a type of application command that is visible in the right click context menu of a message.

Message commands, unlike chat input, do not support options or descriptions.

User Commands

User commands are a type of application command that is visible in the right click context menu of a user.

User commands, unlike chat input, do not support options or descriptions.

Buttons

note

For information on how to use buttons, see How-to Guides - Buttons.

Buttons are interactive components on a Message. Similar to the old-school reaction buttons, these provide cleaner UI/UX than a small reaction button and are the preferred way of handling such inputs now.

Buttons must be inside an ActionRow

caution

You can have up to 5 ActionRows per message, and up to 5 Buttons within each ActionRow.

Action rows with buttons cannot have select menus.

Button Styles

Button styles offer a number of ways for a button to display

StyleDescription
PRIMARYA blurple button
SECONDARYA grey button
SUCCESSA green button
DANGERA red button
LINKA grey button, that navigates to a URL
caution

LINK style buttons cannot have a custom_id and will not send an interaction event when a user clicks on it.

Disabled buttons

Buttons can be disabled to prevent user interaction. When set to disabled the button will appear grayed out.

Emoji Buttons

Buttons can also display an emoji rather than text if desired

Select Menus

note

For information on how to use Select Menus, see How-to Guides - Select Menus.

Select menus allow a dropdown to be displayed on a message itself rather than only inside the command input window.

Like Buttons, select menus must be inside of an ActionRow

caution

You can have up to 5 ActionRows per message, and only one select menu per ActionRow.

Action rows with select menus cannot have buttons.

Auto Complete

note

For information on how to use Auto Complete, see How-to Guides - Auto Complete.

Auto complete allows a bot to give the user suggestions when the user is typing a command option with auto complete enabled. It can be used for a variety of use cases, the most common being to suggest the correct input when more than 25 options are needed. It is only available for STRING, NUMBER, and INTEGER option types and up to 25 suggestions can be provided at a time.

Unlike other interactions, auto complete cannot be deferred and requires only one response within 3 seconds.

Method summary

When you receive an interaction event, you can choose how to handle it, but it must be only one of the following and must be completed within a three-second window after Discord sends the interaction event.

MethodApplication Command events
deferReplyNo message, user sees a loading state
replyInclude a message
MethodAutocomplete events
respondWithSuggestionsUp 25 choices will be displayed
MethodComponent events
deferReplyNo message, user sees a loading state
replyInclude a message
deferEditNo message, user does not see a loading state
editUpdate the message that originated the event

After the initial response is complete, you can work with the interaction using the following methods:

MethodAny DeferrableInteraction event
editReplyUpdate the initial response
getReplyFetch the initial response
deleteReplyDelete the initial response
createFollowupCreate a followup message
editFollowupUpdate a followup message, given its ID
deleteFollowupDelete a followup message, given its ID

Further Reading