diff --git a/docs/Change_Log.md b/docs/Change_Log.md index 1320177621..c8846529be 100644 --- a/docs/Change_Log.md +++ b/docs/Change_Log.md @@ -1,5 +1,21 @@ # Change Log +## Slash Command Permissions + +## April 5, 2021 + +Need to keep some of your Slash Commands safe from prying eyes, or only available to the right people? Slash Commands now support [command permissions](#DOCS_INTERACTIONS_SLASH_COMMANDS/permissions)! + +You can enable or disable a command (guild or global) for a specific user or role in a guild. For now, users will still be able to see the commands, but won't be able to use them. + +New routes have been added to support this functionality: + +- [`GET Guild Application Command Permissions`](#DOCS_INTERACTIONS_SLASH_COMMANDS/getguildapplicationcommandpermissions) +- [`GET Application Command Permissions`](#DOCS_INTERACTIONS_SLASH_COMMANDS/getapplicationcommandpermissions) +- [`PUT Application Command Permissions`](#DOCS_INTERACTIONS_SLASH_COMMANDS/putapplicationcommandpermissions) + +A `default_permission` field has also been added to the [ApplicationCommand](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommand) model. This field allows you to disable commands for everyone in a guild by default, if you prefer to make some of your commands an opt-in experience. + ## Large Bot Sharding Lowered to 150,000 Guilds ## March 15, 2021 diff --git a/docs/interactions/Slash_Commands.md b/docs/interactions/Slash_Commands.md index e514a52467..00fcc4891e 100644 --- a/docs/interactions/Slash_Commands.md +++ b/docs/interactions/Slash_Commands.md @@ -627,6 +627,48 @@ And, done! The JSON looks a bit complicated, but what we've ended up with is a s ![A command with grouped subcommands and parameters. It says /permissions user get with arguments for a user and a channel.](command-with-groups-subcommands-parameters.png) +## Permissions + +Need to keep some of your Slash Commands safe from prying eyes, or only available to the right people? Slash Commands support permission overwrites for all your commands. For both guild _and_ global commands, you can enable or disable a specific user or role in a guild from using a command. + +> info +> For now, if you don't have permission to use a command, they'll show up in the command picker as disabled and unusable. They will not be hidden. + +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: + +```json +{ + "name": "permissions_test", + "description": "A test of default permissions", + "default_permission": false +} +``` + +To enable it just for a moderator role: + +```py +MODERATOR_ROLE_ID = "" +url = "https://discord.com/api/v8/applications//guilds//commands//permissions" + +json = { + "permissions": [ + { + "id": MODERATOR_ROLE_ID, + "type": 1, + "permission": True + } + ] +} + +headers = { + "Authorization": "Bot 123456" +} + +r = requests.put(url, headers=headers, json=json) +``` + ## Endpoints > info @@ -650,6 +692,7 @@ Create a new global command. New global commands will be available in all guilds | name | string | 1-32 character name matching `^[\w-]{1,32}$` | | description | string | 1-100 character description | | options? | array of [ApplicationCommandOption](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommandoption) | the parameters for the command | +| default_permission? | boolean (default `true`) | whether the command is enabled by default when the app is added to a guild | ## Get Global Application Command % GET /applications/{application.id#DOCS_TOPICS_OAUTH2/application-object}/commands/{command.id#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommand} @@ -669,6 +712,7 @@ Edit a global command. Updates will be available in all guilds after 1 hour. Ret | name | string | 1-32 character name matching `^[\w-]{1,32}$` | | description | string | 1-100 character description | | options | array of [ApplicationCommandOption](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommandoption) | the parameters for the command | +| default_permission? | boolean (default `true`) | whether the command is enabled by default when the app is added to a guild | ## Delete Global Application Command % DELETE /applications/{application.id#DOCS_TOPICS_OAUTH2/application-object}/commands/{command.id#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommand} @@ -693,6 +737,7 @@ Create a new guild command. New guild commands will be available in the guild im | name | string | 1-32 character name matching `^[\w-]{1,32}$` | | description | string | 1-100 character description | | options? | array of [ApplicationCommandOption](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommandoption) | the parameters for the command | +| default_permission? | boolean (default `true`) | whether the command is enabled by default when the app is added to a guild | ## Get Guild Application Command % GET /applications/{application.id#DOCS_TOPICS_OAUTH2/application-object}/guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/commands/{command.id#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommand} @@ -712,6 +757,7 @@ Edit a guild command. Updates for guild commands will be available immediately. | name | string | 1-32 character name matching `^[\w-]{1,32}$` | | description | string | 1-100 character description | | options | array of [ApplicationCommandOption](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommandoption) | the parameters for the command | +| default_permission? | boolean (default `true`) | whether the command is enabled by default when the app is added to a guild | ## Delete Guild Application Command % DELETE /applications/{application.id#DOCS_TOPICS_OAUTH2/application-object}/guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/commands/{command.id#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommand} @@ -742,6 +788,77 @@ Edits a followup message for an Interaction. Functions the same as [Edit Webhook Deletes a followup message for an Interaction. Returns `204` on success. +## Get Guild Application Command Permissions % GET /applications/{application.id#DOCS_TOPICS_OAUTH2/application-object}/guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/commands/permissions + +Fetches command permissions for all commands for your application in a guild. Returns an array of [GuildApplicationCommandPermissions](#DOCS_INTERACTIONS_SLASH_COMMANDS/guildapplicationcommandpermissions) objects. + + +## Get Application Command Permissions % GET /applications/{application.id#DOCS_TOPICS_OAUTH2/application-object}/guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/commands/{command.id#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommand}/permissions + +Fetches command permissions for a specific command for your application in a guild. Returns a [GuildApplicationCommandPermissions](#DOCS_INTERACTIONS_SLASH_COMMANDS/guildapplicationcommandpermissions) object. + +## Edit Application Command Permissions % PUT /applications/{application.id#DOCS_TOPICS_OAUTH2/application-object}/guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/commands/{command.id#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommand}/permissions + +> warn +> 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. + +> warn +> Deleting or renaming a command will permanently delete all permissions for that command + +###### JSON Params + +| Field | Type | Description | +| ----- | ---- | ----------- | +| permissions | array of [ApplicationCommandPermissions] | + +## Batch Edit Application Command Permissions % PUT /applications/{application.id#DOCS_TOPICS_OAUTH2/application-object}/guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/commands/permissions + +> warn +> This endpoint will overwrite all existing permissions for all commands in a guild + +Batch edits permissions for all commands in a guild. Takes an array of partial [GuildApplicationCommandPermissions](#DOCS_INTERACTIONS_SLASH_COMMANDS/guildapplicationcommandpermissions) objects including `id` and `permissions`. + +###### Example + +```py +FIRST_COMMAND_ID = "" +SECOND_COMMAND_ID = "" +ADMIN_ROLE_ID = "" + +url = "https://discord.com/api/v8/applications//guilds//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 123456" +} + +r = requests.put(url, headers=headers, json=json) +``` + ## Data Models and Types ## ApplicationCommand @@ -758,6 +875,7 @@ An application command is the base "command" model that belongs to an applicatio | name | string | 1-32 character name matching `^[\w-]{1,32}$` | | description | string | 1-100 character description | | options? | array of [ApplicationCommandOption](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommandoption) | the parameters for the command | +| default_permission? | boolean (default `true`) | whether the command is enabled by default when the app is added to a guild | ## ApplicationCommandOption @@ -795,6 +913,34 @@ If you specify `choices` for an option, they are the **only** valid values for a | name | string | 1-100 character choice name | | value | string or int | value of the choice, up to 100 characters if string | +## GuildApplicationCommandPermissions + +Returned when fetching the permissions for a command in a guild. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| id | snowflake | the id of the command | +| application_id | snowflake | the id of the application the command belongs to | +| guild_id | snowflake | the id of the guild | +| permissions | array of [ApplicationCommandPermissions](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommandpermissions) | the permissions for the command in the guild | + +## ApplicationCommandPermissions + +Application command permissions allow you to enable or disable commands for specific users or roles within a guild. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| id | snowflake | the id of the role or user | +| type | [ApplicationCommandPermissionType](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommandpermissiontype) | role or user | +| permission | boolean | `true` to allow, `false`, to disallow | + +## ApplicationCommandPermissionType + +| Name | Value | +| -----| ----- | +| ROLE | 1 | +| USER | 2 | + ## Interaction An interaction is the base "thing" that is sent when a user invokes a command, and is the same for Slash Commands and other future interaction types.