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
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.
| Name | Value | Note |
|---|---|---|
| SUB_COMMAND | 1 | |
| SUB_COMMAND_GROUP | 2 | Transparent to the user; a way to organize your commands in code |
| STRING | 3 | |
| INTEGER | 4 | Any integer between -2^53 and 2^53 |
| BOOLEAN | 5 | |
| USER | 6 | |
| CHANNEL | 7 | Includes all channel types + categories |
| ROLE | 8 | |
| MENTIONABLE | 9 | Includes all users/roles |
| NUMBER | 10 | Any floating point number between -2^53 and 2^53 |
| ATTACHMENT | 11 | File 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.
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
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
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
| Style | Description |
|---|---|
| PRIMARY | A blurple button |
| SECONDARY | A grey button |
| SUCCESS | A green button |
| DANGER | A red button |
| LINK | A grey button, that navigates to a URL |
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
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
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
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.
| Method | Application Command events |
|---|---|
| deferReply | No message, user sees a loading state |
| reply | Include a message |
| Method | Autocomplete events |
|---|---|
| respondWithSuggestions | Up 25 choices will be displayed |
| Method | Component events |
|---|---|
| deferReply | No message, user sees a loading state |
| reply | Include a message |
| deferEdit | No message, user does not see a loading state |
| edit | Update the message that originated the event |
After the initial response is complete, you can work with the interaction using the following methods:
| Method | Any DeferrableInteraction event |
|---|---|
| editReply | Update the initial response |
| getReply | Fetch the initial response |
| deleteReply | Delete the initial response |
| createFollowup | Create a followup message |
| editFollowup | Update a followup message, given its ID |
| deleteFollowup | Delete a followup message, given its ID |