Skip to content

Slash Commands Permissions #2737

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Apr 7, 2021
Merged

Slash Commands Permissions #2737

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
b8c1ccc
Slash commands permissions
msciotti Mar 25, 2021
de4641a
Permissions example
msciotti Mar 25, 2021
d83b6a6
Casing
msciotti Mar 25, 2021
6e490a5
You are all very helpful and we appreciate you
msciotti Mar 25, 2021
38410f2
PR review
msciotti Apr 5, 2021
9bfef59
default_permissions DM behavior
msciotti Apr 5, 2021
3730106
Document proper response for permissions GET
msciotti Apr 5, 2021
ba84c27
PUT all guild command permissions
msciotti Apr 5, 2021
a57363a
typo
msciotti Apr 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/Change_Log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,21 @@
# Change Log

## Slash Command Permissions

## March XX, 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/getguildapplicationcommandpermissions)
- [`PUT Application Command Permissions`](#DOCS_INTERACTIONS_SLASH_COMMANDS/putapplicationcommandpermissions)

A `default_permissions` 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
Expand Down
54 changes: 54 additions & 0 deletions docs/interactions/Slash_Commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -627,6 +627,17 @@ 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, disabled commands still show up in the command picker, but are unable to be used.

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_permissions` to `False` will disallow _anyone_ in a guild from using the command--even Administrators--unless a specific overwrite is configured.

Check out the [examples in the Endpoints](#DOCS_INTERACTIONS_SLASH_COMMANDS/getglobalapplicationcommandpermissions).

## Endpoints

> info
Expand Down Expand Up @@ -742,6 +753,31 @@ 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}/permissions

Fetches command permissions for all commands for your application in a guild. Returns an array of [ApplicationCommandPermissions](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommandpermissions).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How am I supposed to correlate the permissions and the command they belong to with this route? (if it really does only return an array of ApplicationCommandPermissions, which it might not... I didn't check.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ApplicationCommand.id == ApplicationCommandPermissions.id.

If an application command has no permission overwrites set in the guild, then the array wont contain an ApplicationCommandPermissions object for it.



## 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 an array of [ApplicationCommandPermissions](#DOCS_INTERACTIONS_SLASH_COMMANDS/applicationcommandpermissions).

## 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] |

## Data Models and Types

## ApplicationCommand
Expand All @@ -758,6 +794,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

Expand Down Expand Up @@ -795,6 +832,23 @@ 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 |

## 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.
Expand Down