Application Commands

Application commands are commands that an application can register to Discord. They provide users a first-class way of interacting directly with your application that feels deeply integrated into Discord.

If you specify choices for an option, they are the only valid values for a user to pick

All options have names, and an option can either be a parameter and input value--in which case value will be set--or it can denote a subcommand or group--in which case it will contain a top-level key and another array of options.

value and options are mutually exclusive.

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.

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 within the guild for its commands to work, you no longer need to add for the bot scope or specific permissions.

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_INPUT commands with the same name
• Your app cannot have two guild CHAT_INPUT commands within the same name on the same guild
• Your app cannot have two global USER commands with the same name
• Your app can have a global and guild CHAT_INPUT command with the same name
• Your app can have a global CHAT_INPUT and USER command 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_INPUT commands
• 5 global USER commands
• 5 global MESSAGE commands

As well as the same amount of guild-specific commands per guild.

Global commands are available on all your app's guilds. Global commands are cached for 1 hour. That means that new global commands will fan out slowly across all guilds, and will be guaranteed to be updated in an hour.

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.

To make a global command, make an HTTP POST call like this:

import requests


url = "https://discord.com/api/v8/applications/<my_application_id>/commands"

# This is an example CHAT_INPUT or Slash Command, with a type of 1
json = {
    "name": "blep",
    "type": 1,
    "description": "Send a random adorable animal photo",
    "options": [
        {
            "name": "animal",
            "description": "The type of animal",
            "type": 3,
            "required": True,
            "choices": [
                {
                    "name": "Dog",
                    "value": "animal_dog"
                },
                {
                    "name": "Cat",
                    "value": "animal_cat"
                },
                {
                    "name": "Penguin",
                    "value": "animal_penguin"
                }
            ]
        },
        {
            "name": "only_smol",
            "description": "Whether to show only baby animals",
            "type": 5,
            "required": False
        }
    ]
}

# For authorization, you can use either your bot token
headers = {
    "Authorization": "Bot <my_bot_token>"
}

# or a client credentials token for your app with the applications.commands.update scope
headers = {
    "Authorization": "Bearer <my_credentials_token>"
}

r = requests.post(url, headers=headers, json=json)

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:

import requests


url = "https://discord.com/api/v8/applications/<my_application_id>/guilds/<guild_id>/commands"

# This is an example USER command, with a type of 2
json = {
    "name": "High Five",
    "type": 2
}

# For authorization, you can use either your bot token
headers = {
    "Authorization": "Bot <my_bot_token>"
}

# or a client credentials token for your app with the applications.commands.update scope
headers = {
    "Authorization": "Bearer <my_credentials_token>"
}

r = requests.post(url, headers=headers, json=json)

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, or
• applications/<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.

Full documentation of endpoints can be found here.

Returned when fetching the permissions for a command in a guild.

Application command permissions allow you to enable or disable commands for specific users or roles within a guild.

Need to keep some of your commands safe from prying eyes, or only available to the right people? Commands support permission overwrites! For both guild and global commands of all types, you can enable or disable a specific user or role in a guild from using a command.

You can also set a default_permission on your commands if you want them to be disabled by default when your app is added to a new guild. Setting default_permission to false will disallow anyone in a guild from using the command—even Administrators and guild owners—unless a specific overwrite is configured. It will also disable the command from being usable in DMs.

For example, this command will not be usable by anyone in any guilds by default:

{
  "name": "permissions_test",
  "description": "A test of default permissions",
  "type": 1,
  "default_permission": false
}

To enable it just for a moderator role:

MODERATOR_ROLE_ID = "<moderator_role_id>"
url = "https://discord.com/api/v8/applications/<my_application_id>/guilds/<my_guild_id>/commands/<my_command_id>/permissions"

json = {
    "permissions": [
        {
            "id": MODERATOR_ROLE_ID,
            "type": 1,
            "permission": True
        }
    ]
}

headers = {
    "Authorization": "Bot <my_bot_token>"
}

r = requests.put(url, headers=headers, json=json)

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.

{
  "name": "blep",
  "type": 1,
  "description": "Send a random adorable animal photo",
  "options": [
    {
      "name": "animal",
      "description": "The type of animal",
      "type": 3,
      "required": true,
      "choices": [
        {
          "name": "Dog",
          "value": "animal_dog"
        },
        {
          "name": "Cat",
          "value": "animal_cat"
        },
        {
          "name": "Penguin",
          "value": "animal_penguin"
        }
      ]
    },
    {
      "name": "only_smol",
      "description": "Whether to show only baby animals",
      "type": 5,
      "required": false
    }
  ]
}

When someone uses a slash command, your application will receive an interaction:

{
  "type": 2,
  "token": "A_UNIQUE_TOKEN",
  "member": {
    "user": {
      "id": "53908232506183680",
      "username": "mason",
      "global_name": "Mason",
      "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432",
      "discriminator": "0",
      "public_flags": 131141,
      "avatar_decoration_data": null
    },
    "roles": ["539082325061836999"],
    "premium_since": null,
    "permissions": "2147483647",
    "pending": false,
    "nick": null,
    "mute": false,
    "joined_at": "2017-03-13T19:19:14.040000+00:00",
    "deaf": false
  },
  "id": "786008729715212338",
  "guild_id": "290926798626357999",
  "data": {
    "options": [
      {
        "name": "cardname",
        "value": "The Gitrog Monster"
      }
    ],
    "name": "cardsearch",
    "id": "771825006014889984"
  },
  "channel_id": "645027906669510667"
}

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.

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

  #######

  command
  |
  |__ subcommand-group
      |
      |__ subcommand
  |
  |__ subcommand-group
      |
      |__ subcommand

#######

INVALID

  command
  |
  |__ subcommand-group
      |
      |__ subcommand-group
  |
  |__ subcommand-group
      |
      |__ subcommand-group

  #######

  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.

{
  "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,
          "joined_at": "2021-02-12T18:25:07.972000+00:00",
          "nick": null,
          "pending": false,
          "permissions": "246997699136",
          "premium_since": null,
          "roles": []
        }
      },
      "users": {
        "809850198683418695": {
          "id": "809850198683418695",
          "username": "voltydemo",
          "global_name": "VoltyDemo",
          "avatar": "afc428077119df8aabbbd84b0dc90c74",
          "discriminator": "0",
          "public_flags": 0,
          "bot": true,
          "avatar_decoration_data": null
        }
      }
    },
    "target_id": "809850198683418695",
    "type": 2
  },
  "guild_id": "772904309264089089",
  "id": "867794291820986368",
  "member": {
    "avatar": null,
    "deaf": 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": {
      "id": "167348773423415296",
      "username": "ian",
      "global_name": "Ian",
      "avatar": "a_f03401914fb4f3caa9037578ab980920",
      "discriminator": "0",
      "public_flags": 131141,
      "avatar_decoration_data": null
    }
  },
  "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.

{
  "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": {
            "id": "167348773423415296",
            "username": "ian",
            "global_name": "Ian",
            "avatar": "a_f03401914fb4f3caa9037578ab980920",
            "discriminator": "0",
            "public_flags": 131141,
            "avatar_decoration_data": null
          },
          "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",
  "id": "867793873336926249",
  "member": {
    "avatar": null,
    "deaf": 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": {
      "id": "167348773423415296",
      "username": "ian",
      "global_name": "Ian",
      "avatar": "a_f03401914fb4f3caa9037578ab980920",
      "discriminator": "0",
      "public_flags": 131141,
      "avatar_decoration_data": null
    }
  },
  "token": "UNIQUE_TOKEN",
  "type": 2,
  "version": 1
}

Fetch all of the global commands for your application. Returns an array of application command objects.

Create a new global command. New global commands will be available in all guilds after 1 hour. Returns 201 and an application command object.

Fetch a global command for your application. Returns an application command object.

Edit a global command. Updates will be available in all guilds after 1 hour. Returns 200 and an application command object.

Deletes a global command. Returns 204.

Takes a list of application commands, overwriting existing commands that are registered globally for this application. Updates will be available in all guilds after 1 hour. Returns 200 and a list of application command objects. Commands that do not already exist will count toward daily application command create limits.

Fetch all of the guild commands for your application for a specific guild. Returns an array of application command objects.

Create a new guild command. New guild commands will be available in the guild immediately. Returns 201 and an application command object. If the command did not already exist, it will count toward daily application command create limits.

Fetch a guild command for your application. Returns an application command object.

Edit a guild command. Updates for guild commands will be available immediately. Returns 200 and an application command object.

Delete a guild command. Returns 204 on success.

Takes a list of application commands, overwriting existing commands for the guild. Returns 200 and a list of application command objects.

Fetches command permissions for all commands for your application in a guild. Returns an array of guild application command permissions objects.

Fetches command permissions for a specific command for your application in a guild. Returns a guild application command permissions object.

Edits command permissions for a specific command for your application in a guild. You can only add up to 10 permission overwrites for a command. Returns a GuildApplicationCommandPermissions object.

Batch edits permissions for all commands in a guild. Takes an array of partial guild application command permissions objects including id and permissions.

You can only add up to 10 permission overwrites for a command.

Returns an array of GuildApplicationCommandPermissions objects.

FIRST_COMMAND_ID = "<first_command_id>"
SECOND_COMMAND_ID = "<second_command_id>"
ADMIN_ROLE_ID = "<admin_role_id>"

url = "https://discord.com/api/v8/applications/<my_application_id>/guilds/<my_guild_id>/commands/permissions"

json = [
    {
        "id": FIRST_COMMAND_ID,
        "permissions": [
            {
                "id": ADMIN_ROLE_ID,
                "type": 1,
                "permission": True
            }
        ]
    },
    {
        "id": SECOND_COMMAND_ID,
        "permissions": [
            {
                "id": ADMIN_ROLE_ID,
                "type": 1,
                "permission": False
            }
        ]
    }
]

headers = {
    "Authorization": "Bot <my_bot_token>"
}

r = requests.put(url, headers=headers, json=json)