Application commands are native ways to interact with apps in the Discord client. There are 3 types of commands accessible in different interfaces: the chat input, a message's context menu (top-right menu or right-clicking in a message), and a user's context menu (right-clicking on a user).
CHAT_INPUT command names and command option names must match the following regex ^[-_\p{L}\p{N}\p{sc=Deva}\p{sc=Thai}]{1,32}$ with the unicode flag set. If there is a lowercase variant of any letters used, you must use those. Characters with no lowercase variants and/or uncased letters are still allowed. USER and MESSAGE commands may be mixed case and can include spaces.
| Field | Type | Description | Valid Types |
|---|---|---|---|
| id | snowflake | Unique ID of command | all |
| type? | one of application command type | Type of command, defaults to 1 |
all |
| application_id | snowflake | ID of the parent application | all |
| guild_id? | snowflake | Guild ID of the command, if not global | all |
| name | string | Name of command, 1-32 characters | all |
| name_localizations? | ?dictionary with keys in available locales | Localization dictionary for name field. Values follow the same restrictions as name |
all |
| description | string | Description for CHAT_INPUT commands, 1-100 characters. Empty string for USER and MESSAGE commands |
all |
| description_localizations? | ?dictionary with keys in available locales | Localization dictionary for description field. Values follow the same restrictions as description |
all |
| options? * | array of application command option | Parameters for the command, max of 25 | CHAT_INPUT |
| default_member_permissions | ?string | Set of permissions represented as a bit set | all |
| dm_permission? | boolean | Deprecated (use contexts instead); Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. |
all |
| default_permission? | ?boolean | Not recommended for use as field will soon be deprecated. Indicates whether the command is enabled by default when the app is added to a guild, defaults to true |
all |
| nsfw? | boolean | Indicates whether the command is age-restricted, defaults to false |
all |
| integration_types? | list of integration types | Installation contexts where the command is available, only for globally-scoped commands. Defaults to your app's configured contexts | all |
| contexts? | ?list of interaction context types | Interaction context(s) where the command can be used, only for globally-scoped commands. By default, all interaction context types included for new commands. | all |
| version | snowflake | Autoincrementing version identifier updated during substantial record changes | all |
optionscan only be set for application commands of typeCHAT_INPUT.
default_permission will soon be deprecated. You can instead set default_member_permissions to "0" to disable the command for everyone except admins by default, and/or use contexts to disable globally-scoped commands inside of DMs with your app
| Name | Type | Description |
|---|---|---|
| CHAT_INPUT | 1 | Slash commands; a text-based command that shows up when a user types / |
| USER | 2 | A UI-based command that shows up when you right click or tap on a user |
| MESSAGE | 3 | A UI-based command that shows up when you right click or tap on a message |
Required options must be listed before optional options
| Field | Type | Description | Valid Option Types |
|---|---|---|---|
| type | one of application command option type | Type of option | all |
| name * | string | 1-32 character name | all |
| name_localizations? | ?dictionary with keys in available locales | Localization dictionary for the name field. Values follow the same restrictions as name |
all |
| description | string | 1-100 character description | all |
| description_localizations? | ?dictionary with keys in available locales | Localization dictionary for the description field. Values follow the same restrictions as description |
all |
| required? | boolean | Whether the parameter is required or optional, default false |
all but SUB_COMMAND and SUB_COMMAND_GROUP |
| choices? | array of application command option choice | Choices for the user to pick from, max 25 | STRING, INTEGER, NUMBER |
| options? | array of application command option | If the option is a subcommand or subcommand group type, these nested options will be the parameters or subcommands respectively; up to 25 | SUB_COMMAND , SUB_COMMAND_GROUP |
| channel_types? | array of channel types | The channels shown will be restricted to these types | CHANNEL |
| min_value? | integer for INTEGER options, double for NUMBER options |
The minimum value permitted | INTEGER , NUMBER |
| max_value? | integer for INTEGER options, double for NUMBER options |
The maximum value permitted | INTEGER , NUMBER |
| min_length? | integer | The minimum allowed length (minimum of 0, maximum of 6000) |
STRING |
| max_length? | integer | The maximum allowed length (minimum of 1, maximum of 6000) |
STRING |
| autocomplete? ** | boolean | If autocomplete interactions are enabled for this option | STRING, INTEGER, NUMBER |
namemust be unique within an array of application command options.
** autocomplete may not be set to true if choices are present.
Options using autocomplete are not confined to only use choices given by the application.
| Name | Value | Note |
|---|---|---|
| SUB_COMMAND | 1 | |
| SUB_COMMAND_GROUP | 2 | |
| 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 users and roles |
| NUMBER | 10 | Any double between -2^53 and 2^53 |
| ATTACHMENT | 11 | attachment object |
If you specify choices for an option, they are the only valid values for a user to pick
| Field | Type | Description |
|---|---|---|
| name | string | 1-100 character choice name |
| name_localizations? | ?dictionary with keys in available locales | Localization dictionary for the name field. Values follow the same restrictions as name |
| value | string, integer, or double * | Value for the choice, up to 100 characters if string |
- Type of
valuedepends on the option type that the choice belongs to.
Application commands do not depend on a bot user in the guild; they use the interactions model. To create commands in a guild, your app must be authorized with the applications.commands scope which can be used independently, but is also automatically included with the bot scope.
When requesting this scope, we "shortcut" the OAuth2 flow similar to adding a bot. You don't need to complete the flow, exchange for a token, or any of that.
If your application does not require a bot user in the guild for its commands to work, you don't need to add the bot scope or a permission bitfield to the URL.
Commands can only be registered via HTTP endpoint.
Commands can be scoped either globally or to a specific guild. Global commands are available for every guild that adds your app. An individual app's global commands are also available in DMs if that app has a bot that shares a mutual guild with the user.
Guild commands are specific to the guild you specify when making them. Guild commands are not available in DMs. Command names are unique per application, per type, within each scope (global and guild). That means:
- Your app cannot have two global
CHAT_INPUTcommands with the same name - Your app cannot have two guild
CHAT_INPUTcommands within the same name on the same guild - Your app cannot have two global
USERcommands with the same name - Your app can have a global and guild
CHAT_INPUTcommand with the same name - Your app can have a global
CHAT_INPUTandUSERcommand with the same name - Multiple apps can have commands with the same names
This list is non-exhaustive. In general, remember that command names must be unique per application, per type, and within each scope (global and guild).
An app can have the following number of commands:
- 100 global
CHAT_INPUTcommands - 5 global
USERcommands - 5 global
MESSAGEcommands
As well as the same amount of guild-specific commands per guild.
There is a global rate limit of 200 application command creates per day, per guild
Global commands are available on all your app's guilds.
Global commands have inherent read-repair functionality. That means that if you make an update to a global command, and a user tries to use that command before it has updated for them, Discord will do an internal version check and reject the command, and trigger a reload for that command.
Guild commands are available only within the guild specified on creation. Guild commands update instantly. We recommend you use guild commands for quick testing, and global commands when they're ready for public use.
To make a guild command, make a similar HTTP POST call, but scope it to a specific guild_id:
Commands can be deleted and updated by making DELETE and PATCH calls to the command endpoint. Those endpoints are
applications/<my_application_id>/commands/<command_id>for global commands, orapplications/<my_application_id>/guilds/<guild_id>/commands/<command_id>for guild commands
Because commands have unique names within a type and scope, we treat POST requests for new commands as upserts. That means making a new command with an already-used name for your application will update the existing command.
Detailed documentation about application command endpoints and their parameters are in the endpoints section.
Commands have two sets of contexts on the application command object that let you to configure when and where it can be used:
integration_typesdefines the installation contexts that a command supportscontextsdefines the interaction contexts where a command can be used
Details for both types of command contexts are in the sections below.
Contexts are distinct from, and do not affect, any command permissions for apps installed to a server.
The installation context is where your app was installed—to a server, a user, or both. If your app supports both installation contexts, there may be cases where you want some of your app's commands to only be available for one or the other. For example, maybe your app has a /profile command that is only relevant when it's installed to a user.
A command's supported installation context(s) can be set using the integration_types field when creating or updating a command as long as any included contexts are already supported on the application-level.
A command's value for integration_types may affect which interaction contexts a command is visible in.
The interaction contexts for a command determines where in the Discord client it can be used, and can be configured by setting the contexts field when creating or updating a command.
There are three interaction context types that correspond to different surfaces: GUILD (0), BOT_DM (1), and PRIVATE_CHANNEL (2). However, the PRIVATE_CHANNEL interaction context is only meaningful for commands installed to a user (when the command's integration_types includes USER_INSTALL).
By default, contexts includes all interaction context types.
Application command permissions allow your app to enable or disable commands for up to 100 users, roles, and channels within a guild. Command permissions can also be updated by users in the client if they have the necessary permissions.
Command permissions can only be updated using a Bearer token. Authenticating with a bot token will result in an error.
A command's current permissions can be retrieved using the GET /applications/{application.id}/guilds/{guild.id}/commands/{command.id}/permissions endpoint. The response will include an array called permissions with associated IDs and permission types.
Command permissions can be updated with the PUT /applications/{application.id}/guilds/{guild.id}/commands/{command.id}/permissions endpoint. To call the endpoint, apps must use a Bearer token that's authorized with the applications.commands.permissions.update scope from a user with sufficient permissions. For their permissions to be considered sufficient, all of the following must be true for the authenticating user (not your app or bot user):
- Has permission to Manage Guild and Manage Roles in the guild where the command is being edited
- Has the ability to run the command being edited
- Has permission to manage the resources that will be affected (roles, users, and/or channels depending on the permission types)
This section only applies to the current permissions configuration behavior. It does not apply to guilds that are migrated to the new permissions configuration behavior (starting on December 16, 2022). Read more in the changelog.
The command permissions interface can be accessed in the client by navigating to Server Settings > Integrations, then clicking Manage to the right of an installed app. At the top of the interface, users can edit permissions for a specific user, role, or channel. By default, these top-level permissions will apply to all of an app's commands. However, each permission can also be unsynced and customized for individual commands to provide more granular control.
When the permissions for a specific command are unsynced, meaning it doesn't align with the top-level permissions, the interface will display "Not Synced" to users.
Returned when fetching the permissions for an app's command(s) in a guild.
| Field | Type | Description |
|---|---|---|
| id | snowflake | ID of the command or the application ID |
| application_id | snowflake | ID of the application the command belongs to |
| guild_id | snowflake | ID of the guild |
| permissions | array of application command permissions | Permissions for the command in the guild, max of 100 |
When the id field is the application ID instead of a command ID, the permissions apply to all commands that do not contain explicit overwrites.
Application command permissions allow you to enable or disable commands for specific users, roles, or channels within a guild.
| Field | Type | Description |
|---|---|---|
| id | snowflake | ID of the role, user, or channel. It can also be a permission constant |
| type | application command permission type | role (1), user (2), or channel (3) |
| permission | boolean | true to allow, false, to disallow |
The following constants can be used in the id field for command permissions payloads.
| Permission | Value | Type | Description |
|---|---|---|---|
@everyone |
guild_id |
snowflake | All members in a guild |
| All Channels | guild_id - 1 |
snowflake | All channels in a guild |
| Name | Value |
|---|---|
| ROLE | 1 |
| USER | 2 |
| CHANNEL | 3 |
To allow for fine-tuned access to commands, application command permissions are supported for guild and global commands of all types. Guild members and apps with the necessary permissions can allow or deny specific users and roles from using a command, or toggle commands for entire channels.
Similar to how threads inherit user and role permissions from the parent channel, any command permissions for a channel will apply to the threads it contains.
If you don't have permission to use a command, it will not show up in the command picker. Members with the Administrator permission can use all commands.
Default permissions can be added to a command during creation using the default_member_permissions and context fields. Adding default permissions doesn't require any Bearer token since it's configured during command creation and isn't targeting specific roles, users, or channels.
The default_member_permissions field can be used when creating a command to set the permissions a user must have to use it. The value for default_member_permissions is a bitwise OR-ed set of permissions, serialized as a string. Setting it to "0" will prohibit anyone in a guild from using the command unless a specific overwrite is configured or the user has admin permissions.
You can also include BOT_DM (1) in contexts when setting a global command's interaction contexts to control whether it can be run in DMs with your app. Guild commands don't support the BOT_DM interaction context.
Slash commands—the CHAT_INPUT type—are a type of application command. They're made up of a name, description, and a block of options, which you can think of like arguments to a function. The name and description help users find your command among many others, and the options validate user input as they fill out your command.
Slash commands can also have groups and subcommands to further organize commands. More on those later.
Slash commands can have a maximum of 8000 characters for combined name, description, and value properties for each command, its options (including subcommands and groups), and choices. When localization fields are present, only the longest localization for each field (including the default value) is counted towards the size limit.
Currently, subcommands and subcommand groups all appear at the top level in the command explorer. This may change in the future to include them as nested autocomplete options.
For those developers looking to make more organized and complex groups of commands, look no further than subcommands and groups.
Subcommands organize your commands by specifying actions within a command or group.
Subcommand Groups organize your subcommands by grouping subcommands by similar action or resource within a command.
These are not enforced rules. You are free to use subcommands and groups however you'd like; it's just how we think about them.
Using subcommands or subcommand groups will make your base command unusable. You can't send the base /permissions command as a valid command if you also have /permissions add | remove as subcommands or subcommand groups
We support nesting one level deep within a group, meaning your top level command can contain subcommand groups, and those groups can contain subcommands. That is the only kind of nesting supported. Here's some visual examples:
VALID
command
|
|__ subcommand
|
|__ subcommand
----
VALID
command
|
|__ subcommand-group
|
|__ subcommand
|
|__ subcommand-group
|
|__ subcommand
----
VALID
command
|
|__ subcommand-group
|
|__ subcommand
|
|__ subcommand
-------
INVALID
command
|
|__ subcommand-group
|
|__ subcommand-group
|
|__ subcommand-group
|
|__ subcommand-group
----
INVALID
command
|
|__ subcommand
|
|__ subcommand-group
|
|__ subcommand
|
|__ subcommand-group
Let's look at an example. Let's imagine you run a moderation bot. You want to make a /permissions command that can do the following:
- Get the guild permissions for a user or a role
- Get the permissions for a user or a role on a specific channel
- Change the guild permissions for a user or a role
- Change the permissions for a user or a role on a specific channel
We'll start by defining the top-level information for /permissions:
{
"name": "permissions",
"description": "Get or edit permissions for a user or a role",
"options": []
}
Now we have a command named permissions. We want this command to be able to affect users and roles. Rather than making two separate commands, we can use subcommand groups. We want to use subcommand groups here because we are grouping commands on a similar resource: user or role.
{
"name": "permissions",
"description": "Get or edit permissions for a user or a role",
"options": [
{
"name": "user",
"description": "Get or edit permissions for a user",
"type": 2 // 2 is type SUB_COMMAND_GROUP
},
{
"name": "role",
"description": "Get or edit permissions for a role",
"type": 2
}
]
}
You'll notice that a command like this will not show up in the command explorer. That's because groups are effectively "folders" for commands, and we've made two empty folders. So let's continue.
Now that we've effectively made user and role "folders", we want to be able to either get and edit permissions. Within the subcommand groups, we can make subcommands for get and edit:
{
"name": "permissions",
"description": "Get or edit permissions for a user or a role",
"options": [
{
"name": "user",
"description": "Get or edit permissions for a user",
"type": 2, // 2 is type SUB_COMMAND_GROUP
"options": [
{
"name": "get",
"description": "Get permissions for a user",
"type": 1 // 1 is type SUB_COMMAND
},
{
"name": "edit",
"description": "Edit permissions for a user",
"type": 1
}
]
},
{
"name": "role",
"description": "Get or edit permissions for a role",
"type": 2,
"options": [
{
"name": "get",
"description": "Get permissions for a role",
"type": 1
},
{
"name": "edit",
"description": "Edit permissions for a role",
"type": 1
}
]
}
]
}
Now, we need some arguments! If we chose user, we need to be able to pick a user; if we chose role, we need to be able to pick a role. We also want to be able to pick between guild-level permissions and channel-specific permissions. For that, we can use optional arguments:
{
"name": "permissions",
"description": "Get or edit permissions for a user or a role",
"options": [
{
"name": "user",
"description": "Get or edit permissions for a user",
"type": 2, // 2 is type SUB_COMMAND_GROUP
"options": [
{
"name": "get",
"description": "Get permissions for a user",
"type": 1, // 1 is type SUB_COMMAND
"options": [
{
"name": "user",
"description": "The user to get",
"type": 6, // 6 is type USER
"required": true
},
{
"name": "channel",
"description": "The channel permissions to get. If omitted, the guild permissions will be returned",
"type": 7, // 7 is type CHANNEL
"required": false
}
]
},
{
"name": "edit",
"description": "Edit permissions for a user",
"type": 1,
"options": [
{
"name": "user",
"description": "The user to edit",
"type": 6,
"required": true
},
{
"name": "channel",
"description": "The channel permissions to edit. If omitted, the guild permissions will be edited",
"type": 7,
"required": false
}
]
}
]
},
{
"name": "role",
"description": "Get or edit permissions for a role",
"type": 2,
"options": [
{
"name": "get",
"description": "Get permissions for a role",
"type": 1,
"options": [
{
"name": "role",
"description": "The role to get",
"type": 8, // 8 is type ROLE
"required": true
},
{
"name": "channel",
"description": "The channel permissions to get. If omitted, the guild permissions will be returned",
"type": 7,
"required": false
}
]
},
{
"name": "edit",
"description": "Edit permissions for a role",
"type": 1,
"options": [
{
"name": "role",
"description": "The role to edit",
"type": 8,
"required": true
},
{
"name": "channel",
"description": "The channel permissions to edit. If omitted, the guild permissions will be edited",
"type": 7,
"required": false
}
]
}
]
}
]
}
And, done! The JSON looks a bit complicated, but what we've ended up with is a single command that can be scoped to multiple actions, and then further scoped to a particular resource, and then even further scope with optional arguments. Here's what it looks like all put together.
User commands are application commands that appear on the context menu (right click or tap) of users. They're a great way to surface quick actions for your app that target users. They don't take any arguments, and will return the user on whom you clicked or tapped in the interaction response.
A user must have permission to send text messages in the channel they invoke a user command in. If they don't have this permission, they will receive a 'Permission Denied' error from the interaction.
The description field is not allowed when creating user commands. However, to avoid breaking changes to data models, description will be an empty string (instead of null) when fetching commands.
{
"name": "High Five",
"type": 2
}
When someone uses a user command, your application will receive an interaction:
{
"application_id": "775799577604522054",
"channel_id": "772908445358620702",
"data": {
"id": "866818195033292850",
"name": "context-menu-user-2",
"resolved": {
"members": {
"809850198683418695": {
"avatar": null,
"is_pending": false,
"joined_at": "2021-02-12T18:25:07.972000+00:00",
"nick": null,
"pending": false,
"permissions": "246997699136",
"premium_since": null,
"roles": []
}
},
"users": {
"809850198683418695": {
"avatar": "afc428077119df8aabbbd84b0dc90c74",
"bot": true,
"discriminator": "7302",
"id": "809850198683418695",
"public_flags": 0,
"username": "VoltyDemo"
}
}
},
"target_id": "809850198683418695",
"type": 2
},
"guild_id": "772904309264089089",
"guild_locale": "en-US",
"app_permissions": "442368",
"id": "867794291820986368",
"locale": "en-US",
"member": {
"avatar": null,
"deaf": false,
"is_pending": false,
"joined_at": "2020-11-02T20:46:57.364000+00:00",
"mute": false,
"nick": null,
"pending": false,
"permissions": "274877906943",
"premium_since": null,
"roles": ["785609923542777878"],
"user": {
"avatar": "a_f03401914fb4f3caa9037578ab980920",
"discriminator": "6538",
"id": "167348773423415296",
"public_flags": 1,
"username": "ian"
}
},
"token": "UNIQUE_TOKEN",
"type": 2,
"version": 1
}
Message commands are application commands that appear on the context menu (right click or tap) of messages. They're a great way to surface quick actions for your app that target messages. They don't take any arguments, and will return the message on whom you clicked or tapped in the interaction response.
The description field is not allowed when creating message commands. However, to avoid breaking changes to data models, description will be an empty string (instead of null) when fetching commands.
{
"name": "Bookmark",
"type": 3
}
When someone uses a message command, your application will receive an interaction:
{
"application_id": "775799577604522054",
"channel_id": "772908445358620702",
"data": {
"id": "866818195033292851",
"name": "context-menu-message-2",
"resolved": {
"messages": {
"867793854505943041": {
"attachments": [],
"author": {
"avatar": "a_f03401914fb4f3caa9037578ab980920",
"discriminator": "6538",
"id": "167348773423415296",
"public_flags": 1,
"username": "ian"
},
"channel_id": "772908445358620702",
"components": [],
"content": "some message",
"edited_timestamp": null,
"embeds": [],
"flags": 0,
"id": "867793854505943041",
"mention_everyone": false,
"mention_roles": [],
"mentions": [],
"pinned": false,
"timestamp": "2021-07-22T15:42:57.744000+00:00",
"tts": false,
"type": 0
}
}
},
"target_id": "867793854505943041",
"type": 3
},
"guild_id": "772904309264089089",
"guild_locale": "en-US",
"app_permissions": "442368",
"id": "867793873336926249",
"locale": "en-US",
"member": {
"avatar": null,
"deaf": false,
"is_pending": false,
"joined_at": "2020-11-02T20:46:57.364000+00:00",
"mute": false,
"nick": null,
"pending": false,
"permissions": "274877906943",
"premium_since": null,
"roles": ["785609923542777878"],
"user": {
"avatar": "a_f03401914fb4f3caa9037578ab980920",
"discriminator": "6538",
"id": "167348773423415296",
"public_flags": 1,
"username": "ian"
}
},
"token": "UNIQUE_TOKEN",
"type": 2,
"version": 1
}
Autocomplete interactions allow your application to dynamically return option suggestions to a user as they type.
An autocomplete interaction can return partial data for option values. Your application will receive partial data for any existing user input, as long as that input passes client-side validation. For example, you may receive partial strings, but not invalid numbers. The option the user is currently typing will be sent with a focused: true boolean field and options the user has already filled will also be sent but without the focused field. This is a special case where options that are otherwise required might not be present, due to the user not having filled them yet.
This validation is client-side only.
{
"type": 4,
"data": {
"id": "816437322781949972",
"name": "airhorn",
"type": 1,
"version": "847194950382780532",
"options": [
{
"type": 3,
"name": "variant",
"value": "data a user is typ",
"focused": true
}
]
}
}
Application commands can be localized, which will cause them to use localized names and descriptions depending on the client's selected language. This is entirely optional. Localization is available for names and descriptions of commands, subcommands, and options, as well as the names of choices, by submitting the appropriate name_localizations and description_localizations fields when creating or updating the application command.
Application commands may be partially localized - not all available locales are required, nor do different fields within a command need to support the same set of locales. If a locale is not present in a localizations dictionary for a field, users in that locale will see the default value for that field. It's not necessary to fill out all locales with the default value. Any localized values that are identical to the default will be ignored.
Localized option names are subject to an additional constraint, which is that they must be distinct from all other default option names of that command, as well as all other option names within that locale on that command.
When taking advantage of command localization, the interaction payload received by your client will still use default command, subcommand, and option names. To localize your interaction response, you can determine the client's selected language by using the locale key in the interaction payload.
An application command furnished with localizations might look like this:
{
"name": "birthday",
"type": 1,
"description": "Wish a friend a happy birthday",
"name_localizations": {
"zh-CN": "生日",
"el": "γενέθλια"
},
"description_localizations": {
"zh-CN": "祝你朋友生日快乐"
},
"options": [
{
"name": "age",
"type": 4,
"description": "Your friend's age",
"name_localizations": {
"zh-CN": "岁数"
},
"description_localizations": {
"zh-CN": "你朋友的岁数"
}
}
]
}
While most endpoints that return application command objects will return the name_localizations and description_localizations fields, some will not by default. This includes GET endpoints that return all of an application's guild or global commands. Instead, those endpoints will supply additional name_localized or description_localized fields, which only contain the localization relevant to the requester's locale. (The full dictionaries can still be obtained by supplying the appropriate query argument).
For example, if a batch GET request were made with locale zh-CN, including the above command, the returned object would look as follows:
{
"name": "birthday",
"type": 1,
"description": "Wish a friend a happy birthday",
"name_localized": "生日",
"description_localized": "祝你朋友生日快乐",
"options": [
{
"name": "age",
"type": 4,
"description": "Your friend's age",
"name_localized": "岁数",
"description_localized": "你朋友的岁数",
}
]
}
If the requester's locale is not found in a localizations dictionary, then the corresponding name_localization or description_localization for that field will also not be present.
Locale is determined by looking at the X-Discord-Locale header, then the Accept-Language header if not present, then lastly the user settings locale.
A command that contains age-restricted content should have the nsfw field set to true upon creation or update. Marking a command as age-restricted will limit who can see and access the command, and from which channels.
Apps with discovery enabled (which is required to appear in the App Directory) cannot contain any age-restricted commands or content.
To use an age-restricted command, a user must be 18 years or older and access the command from either:
- an age-restricted channel or
- a DM with the app after enabling age-restricted commands within their User Settings.
Details about accessing and using age-restricted commands is in the Help Center.
For authorization, all endpoints take either a bot token or client credentials token for your application
GET/applications/{application.id}/commands
The objects returned by this endpoint may be augmented with additional fields if localization is active.
Fetch all of the global commands for your application. Returns an array of application command objects.
| Field | Type | Description |
|---|---|---|
| with_localizations? | boolean | Whether to include full localization dictionaries (name_localizations and description_localizations) in the returned objects, instead of the name_localized and description_localized fields. Default false. |
POST/applications/{application.id}/commands
Creating a command with the same name as an existing command for your application will overwrite the old command.
Create a new global command. Returns 201 if a command with the same name does not already exist, or a 200 if it does (in which case the previous command will be overwritten). Both responses include an application command object.
| Field | Type | Description |
|---|---|---|
| name | string | Name of command, 1-32 characters |
| name_localizations? | ?dictionary with keys in available locales | Localization dictionary for the name field. Values follow the same restrictions as name |
| description? | string | 1-100 character description for CHAT_INPUT commands |
| description_localizations? | ?dictionary with keys in available locales | Localization dictionary for the description field. Values follow the same restrictions as description |
| options? | array of application command option | the parameters for the command, max of 25 |
| default_member_permissions? | ?string | Set of permissions represented as a bit set |
| dm_permission? | ?boolean | Deprecated (use contexts instead); Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. |
| default_permission? | boolean | Replaced by default_member_permissions and will be deprecated in the future. Indicates whether the command is enabled by default when the app is added to a guild. Defaults to true |
| integration_types? | list of integration types | Installation context(s) where the command is available |
| contexts? | list of interaction context types | Interaction context(s) where the command can be used |
| type? | one of application command type | Type of command, defaults 1 if not set |
| nsfw? | boolean | Indicates whether the command is age-restricted |
GET/applications/{application.id}/commands/{command.id}
Fetch a global command for your application. Returns an application command object.
PATCH/applications/{application.id}/commands/{command.id}
All parameters for this endpoint are optional.
Edit a global command. Returns 200 and an application command object. All fields are optional, but any fields provided will entirely overwrite the existing values of those fields.
| Field | Type | Description |
|---|---|---|
| name? | string | Name of command, 1-32 characters |
| name_localizations? | ?dictionary with keys in available locales | Localization dictionary for the name field. Values follow the same restrictions as name |
| description? | string | 1-100 character description |
| description_localizations? | ?dictionary with keys in available locales | Localization dictionary for the description field. Values follow the same restrictions as description |
| options? | array of application command option | the parameters for the command |
| default_member_permissions? | ?string | Set of permissions represented as a bit set |
| dm_permission? | ?boolean | Deprecated (use contexts instead); Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. |
| default_permission? | boolean | Replaced by default_member_permissions and will be deprecated in the future. Indicates whether the command is enabled by default when the app is added to a guild. Defaults to true |
| integration_types? | list of integration types | Installation context(s) where the command is available |
| contexts? | list of interaction context types | Interaction context(s) where the command can be used |
| nsfw? | boolean | Indicates whether the command is age-restricted |
DELETE/applications/{application.id}/commands/{command.id}
Deletes a global command. Returns 204 No Content on success.
PUT/applications/{application.id}/commands
Takes a list of application commands, overwriting the existing global command list for this application. Returns 200 and a list of application command objects. Commands that do not already exist will count toward daily application command create limits.
This will overwrite all types of application commands: slash commands, user commands, and message commands.
GET/applications/{application.id}/guilds/{guild.id}/commands
The objects returned by this endpoint may be augmented with additional fields if localization is active.
Fetch all of the guild commands for your application for a specific guild. Returns an array of application command objects.
| Field | Type | Description |
|---|---|---|
| with_localizations? | boolean | Whether to include full localization dictionaries (name_localizations and description_localizations) in the returned objects, instead of the name_localized and description_localized fields. Default false. |
POST/applications/{application.id}/guilds/{guild.id}/commands
Creating a command with the same name as an existing command for your application will overwrite the old command.
Create a new guild command. New guild commands will be available in the guild immediately. Returns 201 if a command with the same name does not already exist, or a 200 if it does (in which case the previous command will be overwritten). Both responses include an application command object.
| Field | Type | Description |
|---|---|---|
| name | string | Name of command, 1-32 characters |
| name_localizations? | ?dictionary with keys in available locales | Localization dictionary for the name field. Values follow the same restrictions as name |
| description? | string | 1-100 character description for CHAT_INPUT commands |
| description_localizations? | ?dictionary with keys in available locales | Localization dictionary for the description field. Values follow the same restrictions as description |
| options? | array of application command option | Parameters for the command, max of 25 |
| default_member_permissions? | ?string | Set of permissions represented as a bit set |
| default_permission? | boolean | Replaced by default_member_permissions and will be deprecated in the future. Indicates whether the command is enabled by default when the app is added to a guild. Defaults to true |
| type? | one of application command type | Type of command, defaults 1 if not set |
| nsfw? | boolean | Indicates whether the command is age-restricted |
GET/applications/{application.id}/guilds/{guild.id}/commands/{command.id}
Fetch a guild command for your application. Returns an application command object.
PATCH/applications/{application.id}/guilds/{guild.id}/commands/{command.id}
All parameters for this endpoint are optional.
Edit a guild command. Updates for guild commands will be available immediately. Returns 200 and an application command object. All fields are optional, but any fields provided will entirely overwrite the existing values of those fields.
| Field | Type | Description |
|---|---|---|
| name? | string | Name of command, 1-32 characters |
| name_localizations? | ?dictionary with keys in available locales | Localization dictionary for the name field. Values follow the same restrictions as name |
| description? | string | 1-100 character description |
| description_localizations? | ?dictionary with keys in available locales | Localization dictionary for the description field. Values follow the same restrictions as description |
| options? | array of application command option | Parameters for the command, max of 25 |
| default_member_permissions? | ?string | Set of permissions represented as a bit set |
| default_permission? | boolean | Replaced by default_member_permissions and will be deprecated in the future. Indicates whether the command is enabled by default when the app is added to a guild. Defaults to true |
| nsfw? | boolean | Indicates whether the command is age-restricted |
DELETE/applications/{application.id}/guilds/{guild.id}/commands/{command.id}
Delete a guild command. Returns 204 No Content on success.
PUT/applications/{application.id}/guilds/{guild.id}/commands
Takes a list of application commands, overwriting the existing command list for this application for the targeted guild. Returns 200 and a list of application command objects.
This will overwrite all types of application commands: slash commands, user commands, and message commands.
| Field | Type | Description |
|---|---|---|
| id? | snowflake | ID of the command, if known |
| name | string | Name of command, 1-32 characters |
| name_localizations? | ?dictionary with keys in available locales | Localization dictionary for the name field. Values follow the same restrictions as name |
| description | string | 1-100 character description |
| description_localizations? | ?dictionary with keys in available locales | Localization dictionary for the description field. Values follow the same restrictions as description |
| options? | array of application command option | Parameters for the command |
| default_member_permissions? | ?string | Set of permissions represented as a bit set |
| dm_permission? | ?boolean | Deprecated (use contexts instead); Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. |
| default_permission? | boolean | Replaced by default_member_permissions and will be deprecated in the future. Indicates whether the command is enabled by default when the app is added to a guild. Defaults to true |
| integration_types | list of integration types | Installation context(s) where the command is available, defaults to GUILD_INSTALL ([0]) |
| contexts | list of interaction context types | Interaction context(s) where the command can be used, defaults to all contexts [0,1,2] |
| type? | one of application command type | Type of command, defaults 1 if not set |
| nsfw? | boolean | Indicates whether the command is age-restricted |
GET/applications/{application.id}/guilds/{guild.id}/commands/permissions
Fetches permissions for all commands for your application in a guild. Returns an array of guild application command permissions objects.
GET/applications/{application.id}/guilds/{guild.id}/commands/{command.id}/permissions
Fetches permissions for a specific command for your application in a guild. Returns a guild application command permissions object.
PUT/applications/{application.id}/guilds/{guild.id}/commands/{command.id}/permissions
This endpoint will overwrite existing permissions for the command in that guild
Edits command permissions for a specific command for your application in a guild and returns a guild application command permissions object. Fires an Application Command Permissions Update Gateway event.
You can add up to 100 permission overwrites for a command.
This endpoint requires authentication with a Bearer token that has permission to manage the guild and its roles. For more information, read above about application command permissions.
Deleting or renaming a command will permanently delete all permissions for the command
| Field | Type | Description |
|---|---|---|
| permissions | array of application command permissions | Permissions for the command in the guild |
PUT/applications/{application.id}/guilds/{guild.id}/commands/permissions
This endpoint has been disabled with updates to command permissions (Permissions v2). Instead, you can edit each application command permissions (though you should be careful to handle any potential rate limits).