Application Commands - Discord Developer Platform

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

Application Command Object

Application Command Naming

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. USER and MESSAGE commands may be mixed case and can include spaces.

Application Command Structure

Field	Type	Description	Valid Types
id	snowflake	Unique ID of command	all
type?	one of command types	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	all
options?*	array of command options	Parameters for the command, max of 25	CHAT_INPUT
default_member_permissions	?string	Set of permissions represented as a bit set	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	all
contexts?	?list of interaction context types	Interaction context(s) where the command can be used, only for globally-scoped commands	all
version	snowflake	Autoincrementing version identifier updated during substantial record changes	all
handler?	one of entry point command handler types	Determines whether the interaction is handled by the app’s interactions handler or by Discord	PRIMARY_ENTRY_POINT

* options can only be set for application commands of type CHAT_INPUT.

Application Command Types

Name	Value	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
PRIMARY_ENTRY_POINT	4	A UI-based command that represents the primary way to invoke an app’s Activity

Application Command Option Structure

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	Localization dictionary for the `name` field	all
description	string	1-100 character description	all
description_localizations?	?dictionary	Localization dictionary for the `description` field	all
required?	boolean	Whether the parameter is required or optional, default `false`	all but `SUB_COMMAND` and `SUB_COMMAND_GROUP`
choices?	array of option choices	Choices for the user to pick from, max 25	`STRING`, `INTEGER`, `NUMBER`
options?	array of command options	If the option is a subcommand or subcommand group type, these nested options will be the parameters or subcommands	`SUB_COMMAND`, `SUB_COMMAND_GROUP`
channel_types?	array of channel types	The channels shown will be restricted to these types	`CHANNEL`
min_value?	integer or double	The minimum value permitted	`INTEGER`, `NUMBER`
max_value?	integer or double	The maximum value permitted	`INTEGER`, `NUMBER`
min_length?	integer	The minimum allowed length (min 0, max 6000)	`STRING`
max_length?	integer	The maximum allowed length (min 1, max 6000)	`STRING`
autocomplete?**	boolean	If autocomplete interactions are enabled for this option	`STRING`, `INTEGER`, `NUMBER`

* name must be unique within an array of 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.

Application Command Option Type

Name	Value	Note
SUB_COMMAND	1
SUB_COMMAND_GROUP	2
STRING	3
INTEGER	4	Any integer between -2^53+1 and 2^53-1
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

Application Command Option Choice Structure

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 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 value depends on the option type that the choice belongs to.

Entry Point Command Handler Types

Name	Value	Note
APP_HANDLER	1	The app handles the interaction using an interaction token
DISCORD_LAUNCH_ACTIVITY	2	Discord handles the interaction by launching an Activity and sending a follow-up message without coordinating with the app

Authorizing Your Application

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 is automatically included with the bot scope. 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.

Registering a Command

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 and are not available in DMs. Command names are unique per application, per type, within each scope (global and guild). For example:

Your app cannot have two global CHAT_INPUT commands with the same name
Your app cannot have two guild CHAT_INPUT commands with the same name on the same guild
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

An app can have the following number of commands:

100 global CHAT_INPUT commands
15 global USER commands
15 global MESSAGE commands
1 global PRIMARY_ENTRY_POINT command

For all command types except PRIMARY_ENTRY_POINT, you can have the same number of guild-specific commands per guild.

There is a global rate limit of 200 application command creates per day, per guild.

Making a Global Command

Global commands are available on all your app’s guilds. They have inherent read-repair functionality: if a user tries to use a command before it has updated, Discord will do a version check, reject the command, and trigger a reload.

import requests

url = "https://discord.com/api/v10/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
        }
    ]
}

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

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

Making a Guild Command

Guild commands update instantly. We recommend using guild commands for quick testing, and global commands when they’re ready for public use.

import requests

url = "https://discord.com/api/v10/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
}

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

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

Updating and Deleting a Command

Commands can be deleted and updated by making DELETE and PATCH calls to the command endpoint:

applications/<my_application_id>/commands/<command_id> for global commands
applications/<my_application_id>/guilds/<guild_id>/commands/<command_id> for guild commands

Because commands have unique names within a type and scope, POST requests for new commands act as upserts—making a new command with an already-used name will update the existing command.

Contexts

Commands have two sets of contexts on the application command object that let you configure when and where they can be used:

integration_types — defines the installation contexts a command supports
contexts — defines the interaction contexts where a command can be used

Contexts are distinct from, and do not affect, any command permissions for apps installed to a server.

Installation Context

The installation context is where your app was installed—to a server, a user, or both. A command’s supported installation context(s) can be set using the integration_types field when creating or updating a command.

Interaction Contexts

The interaction contexts for a command determines where in the Discord client it can be used. There are three interaction context types that correspond to different surfaces: GUILD (0), BOT_DM (1), and PRIVATE_CHANNEL (2).

Permissions

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 only be updated using a Bearer token. Authenticating with a bot token will result in an error.

Using Default Permissions

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

{
    "name": "permissions_test",
    "description": "A test of default permissions",
    "type": 1,
    "default_member_permissions": "0"
}

Or enable it only for users with the MANAGE_GUILD permission:

permissions = str(1 << 5)

command = {
    "name": "permissions_test",
    "description": "A test of default permissions",
    "type": 1,
    "default_member_permissions": permissions
}

Application Command Permissions Structure

Field	Type	Description
id	snowflake	ID of the role, user, or channel
type	application command permission type	role (`1`), user (`2`), or channel (`3`)
permission	boolean	`true` to allow, `false` to disallow

Application Command Permission Type

Name	Value
ROLE	1
USER	2
CHANNEL	3

Permission Constants

Permission	Value	Type	Description
`@everyone`	`guild_id`	snowflake	All members in a guild
All Channels	`guild_id - 1`	snowflake	All channels in a guild

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.

Slash Commands

Slash commands—the CHAT_INPUT type—are made up of a name, description, and a block of options. They can also have groups and subcommands to further organize commands.

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.

Example Slash Command

{
    "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
        }
    ]
}

Example Slash Command Interaction

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

Subcommands and Subcommand 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.

Using subcommands or subcommand groups will make your base command unusable. You can’t send /permissions as a valid command if you also have /permissions add | remove as subcommands.

Nesting is supported one level deep: your top level command can contain subcommand groups, and those groups can contain subcommands. That is the only kind of nesting supported.

VALID

command
|__ subcommand
|__ subcommand

VALID

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

INVALID

command
|__ subcommand-group
    |__ subcommand-group

User Commands

User commands are application commands that appear on the context menu (right click or tap) of users. They don’t take any arguments and return the user on whom you clicked.

A user must have permission to send text messages in the channel they invoke a user command in.

{
    "name": "High Five",
    "type": 2
}

Example User Command 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",
    "id": "867794291820986368",
    "locale": "en-US",
    "token": "UNIQUE_TOKEN",
    "type": 2,
    "version": 1
}

Message Commands

Message commands appear on the context menu (right click or tap) of messages. They return the message on which you clicked.

{
    "name": "Bookmark",
    "type": 3
}

Example Message Command 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",
    "id": "867793873336926249",
    "token": "UNIQUE_TOKEN",
    "type": 2,
    "version": 1
}

Entry Point Commands

An Entry Point command serves as the primary way for users to open an app’s Activity from the App Launcher. For the Entry Point command to be visible to users, an app must have Activities enabled.

{
    "name": "launch",
    "description": "Launch Racing with Friends",
    "type": 4,
    "handler": 2
}

Entry Point Handlers

When a user invokes an app’s Entry Point command, the value of handler determines how the interaction is handled:

For APP_HANDLER (1), the app is responsible for responding to the interaction. It can respond by launching the app’s associated Activity using the LAUNCH_ACTIVITY (type 12) interaction callback type.
For DISCORD_LAUNCH_ACTIVITY (2), Discord handles the interaction automatically by launching the associated Activity and sending a message to the channel.

Default Entry Point Command

When you enable Activities, an Entry Point command named “Launch” is automatically created with DISCORD_LAUNCH_ACTIVITY (2) as the handler. You can retrieve its details by calling the Get Global Application Commands endpoint.

Autocomplete

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. The option the user is currently typing will be sent with "focused": true.

Client-side 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
      }
    ]
  }
}

Localization

Application commands can be localized so they use localized names and descriptions depending on the client’s selected language. Localization is available for names and descriptions of commands, subcommands, options, and choice names via name_localizations and description_localizations fields. Application commands may be partially localized—not all available locales are required. If a locale is not present, users in that locale will see the default value.

{
  "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": "岁数"
      }
    }
  ]
}

Locale Fallbacks

Locale	Fallback
en-US	en-GB
en-GB	en-US
es-419	es-ES

Include your default value in its proper locale key to avoid unexpected fallback behavior.

Age-Restricted Commands

A command with age-restricted content should have the nsfw field set to true upon creation or update. To use an age-restricted command, a user must be 18 years or older and access the command from an age-restricted channel or a DM with the app after enabling age-restricted commands in their User Settings.

Apps with discovery enabled cannot contain any age-restricted commands or content.

Endpoints

For authorization, all endpoints take either a bot token or client credentials token for your application.

Get Global Application Commands

GET /applications/{application.id}/commands Fetch all global commands for your application. Returns an array of application command objects.

Create Global Application Command

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 doesn’t already exist, or 200 if it does (in which case the previous command will be overwritten).

Edit Global Application Command

PATCH /applications/{application.id}/commands/{command.id} Edit a global command. Returns 200 and an application command object. All fields are optional but will entirely overwrite the existing values of those fields.

Delete Global Application Command

DELETE /applications/{application.id}/commands/{command.id} Deletes a global command. Returns 204 No Content on success.

Bulk Overwrite Global Application Commands

PUT /applications/{application.id}/commands

This will overwrite all types of application commands: slash commands, user commands, and message commands.

Takes a list of application commands, overwriting the existing global command list for this application.

Get Guild Application Commands

GET /applications/{application.id}/guilds/{guild.id}/commands Fetch all guild commands for your application for a specific guild.

Create Guild Application Command

POST /applications/{application.id}/guilds/{guild.id}/commands Create a new guild command. New guild commands will be available in the guild immediately.

Edit Guild Application Command

PATCH /applications/{application.id}/guilds/{guild.id}/commands/{command.id} Edit a guild command. Updates are available immediately.

Delete Guild Application Command

DELETE /applications/{application.id}/guilds/{guild.id}/commands/{command.id} Delete a guild command. Returns 204 No Content on success.

Bulk Overwrite Guild Application Commands

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.

Get Guild Application Command Permissions

GET /applications/{application.id}/guilds/{guild.id}/commands/permissions Fetches permissions for all commands for your application in a guild.

Get Application Command Permissions

GET /applications/{application.id}/guilds/{guild.id}/commands/{command.id}/permissions Fetches permissions for a specific command for your application in a guild.

Edit Application Command Permissions

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. Requires a Bearer token with applications.commands.permissions.update scope.

Introduction

Platform Overview

Bots & Interactions

Monetization & Discovery

Policies

​Application Command Object

​Application Command Naming

​Application Command Structure

​Application Command Types

​Application Command Option Structure

​Application Command Option Type

​Application Command Option Choice Structure

​Entry Point Command Handler Types

​Authorizing Your Application

​Registering a Command

​Making a Global Command

​Making a Guild Command

​Updating and Deleting a Command

​Contexts

​Installation Context

​Interaction Contexts

​Permissions

​Using Default Permissions

​Application Command Permissions Structure

​Application Command Permission Type

​Permission Constants

​Slash Commands

​Example Slash Command

​Subcommands and Subcommand Groups

​User Commands

​Message Commands

​Entry Point Commands

​Entry Point Handlers

​Default Entry Point Command

​Autocomplete

​Localization

​Locale Fallbacks

​Age-Restricted Commands

​Endpoints

​Get Global Application Commands

​Create Global Application Command

​Edit Global Application Command

​Delete Global Application Command

​Bulk Overwrite Global Application Commands

​Get Guild Application Commands

​Create Guild Application Command

​Edit Guild Application Command

​Delete Guild Application Command

​Bulk Overwrite Guild Application Commands

​Get Guild Application Command Permissions

​Get Application Command Permissions

​Edit Application Command Permissions

Application Command Object

Application Command Naming

Application Command Structure

Application Command Types

Application Command Option Structure

Application Command Option Type

Application Command Option Choice Structure

Entry Point Command Handler Types

Authorizing Your Application

Registering a Command

Making a Global Command

Making a Guild Command

Updating and Deleting a Command

Contexts

Installation Context

Interaction Contexts

Permissions

Using Default Permissions

Application Command Permissions Structure

Application Command Permission Type

Permission Constants

Slash Commands

Example Slash Command

Subcommands and Subcommand Groups

User Commands

Message Commands

Entry Point Commands

Entry Point Handlers

Default Entry Point Command

Autocomplete

Localization

Locale Fallbacks

Age-Restricted Commands

Endpoints

Get Global Application Commands

Create Global Application Command

Edit Global Application Command

Delete Global Application Command

Bulk Overwrite Global Application Commands

Get Guild Application Commands

Create Guild Application Command

Edit Guild Application Command

Delete Guild Application Command

Bulk Overwrite Guild Application Commands

Get Guild Application Command Permissions

Get Application Command Permissions

Edit Application Command Permissions