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.
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 |