Slash Commands and Interactions (#2295)

* Slash Commands and Interactions documentation * Nits and TODOs * create, not created * Fix python make command example * More endpoints * groups and subcommands * should be application id * interaction create event * Rate limits and maximums * http verbs * Signature validation examples * More limits * a better intro * swap code samples for sig validation * global -> guild, list -> array * Fix missing id params * wrong role type * NOW the right role type * PR Fixes and Application Object - Added application object - roles are a string - applications.commands.update scope * application on ready * headings * 10s all the way down * grammar and spelling * broken links * more broken links * what even? * options -> object * one more broken link * make things less dangerous * not webhook * Broken links and spelling Co-authored-by: Advaith <[email protected]> * fix old merge issue in webhook edit * subcommand warning * PR feedback * add s * spelling Co-authored-by: Advaith <[email protected]>
discord · Dec 15, 2020 · aa200b5 · aa200b5
1 parent 689c530
commit aa200b5
Show file tree

Hide file tree

Showing 10 changed files with 900 additions and 28 deletions.
diff --git a/docs/Change_Log.md b/docs/Change_Log.md
@@ -1,5 +1,16 @@
 # Change Log
 
+## Slash Commands and Interactions
+#### December 15, 2020
+
+Slash Commands are here! There's a _lot_ to cover, so go check out specific documentation under [Slash Commands](#DOCS_INTERACTIONS_SLASH_COMMANDS/).
+
+Slash Commands include some new features for webhooks as well:
+
+- Webhooks can now update previously-sent messages from the same webhook using [Edit Webhook Message](#DOCS_RESOURCES_WEBHOOK/edit-webhook-message) and [Delete Webhook Message](#DOCS_RESOURCES_WEBHOOK/delete-webhook-message)
+
+This PR also documents the `application` field on the `READY` gateway event, which is a partial [application object](#DOCS_TOPICS_OAUTH2/application-object) containing `id` and `flags`.
+
 ## Inline Replies
 
 #### November 16, 2020

diff --git a/docs/interactions/Slash_Commands.md b/docs/interactions/Slash_Commands.md
diff --git a/docs/resources/Channel.md b/docs/resources/Channel.md
@@ -218,7 +218,7 @@ Represents a message sent in a channel within Discord.
 ###### Message Types
 
 > warn
-> Replies only have type `19` in API v8. In v6, they are still type `0`.
+> Type `19` and `20` are only in API v8. In v6, they are still type `0`.
 
 | Type                                   | Value |
 |----------------------------------------|-------|
@@ -238,6 +238,7 @@ Represents a message sent in a channel within Discord.
 | GUILD_DISCOVERY_DISQUALIFIED           | 14    |
 | GUILD_DISCOVERY_REQUALIFIED            | 15    |
 | REPLY                                  | 19    |
+| APPLICATION_COMMAND                    | 20    |
 
 ###### Message Activity Structure
 

diff --git a/docs/resources/Webhook.md b/docs/resources/Webhook.md
@@ -152,6 +152,8 @@ Add a new webhook to your GitHub repo (in the repo's settings), and use this end
 
 ## Edit Webhook Message % PATCH /webhooks/{webhook.id#DOCS_RESOURCES_WEBHOOK/webhook-object}/{webhook.token#DOCS_RESOURCES_WEBHOOK/webhook-object}/messages/{message.id#DOCS_RESOURCES_CHANNEL/message-object}
 
+Edits a previously-sent webhook message from the same token.
+
 > info
 > All parameters to this endpoint are optional and nullable.
 
@@ -165,4 +167,4 @@ Add a new webhook to your GitHub repo (in the repo's settings), and use this end
 
 # Delete Webhook Message % DELETE /webhooks/{webhook.id#DOCS_RESOURCES_WEBHOOK/webhook-object}/{webhook.token#DOCS_RESOURCES_WEBHOOK/webhook-object}/messages/{message.id#DOCS_RESOURCES_CHANNEL/message-object}
 
-Deletes a message that was created by the webhook. Returns a 204 NO CONTENT response on success.
+Deletes a message that was created by the webhook. Returns a 204 NO CONTENT response on success.
diff --git a/docs/topics/Community_Resources.md b/docs/topics/Community_Resources.md
@@ -39,6 +39,13 @@ Many of these libraries are represented in the [unofficial, community-driven Dis
 | [Sword](https://github.com/Azoy/Sword)                       | Swift      |
 | [discordeno](https://github.com/discordeno/discordeno)       | TypeScript |
 
+## Interactions
+
+[Interactions and Slash Commands](#DOCS_INTERACTIONS_SLASH_COMMANDS/) are the great, new way of making a Discord bot. The following open-source libraries provide help for the security and authentication checks that are mandatory if you are receiving Interactions via outgoing webhook. They also include some types for the Interactions data models.
+
+- [discord-interactions-js](https://github.com/discord/discord-interactions-js)
+- [discord-interactions-python](https://github.com/discord/discord-interactions-python)
+
 ## Game SDK Tools
 
 Discord Game SDK's lobby and networking layer shares similarities with other gaming platforms (i.e. Valve's Steamworks SDK). The following open source library provides developers a uniform interface for these shared features and can simplify developing for multiple platforms. Note: this library is tailored for Unity3D development.

diff --git a/docs/topics/Gateway.md b/docs/topics/Gateway.md
@@ -409,6 +409,7 @@ Events are payloads sent over the socket to a client that correspond to events i
 | [Voice State Update](#DOCS_TOPICS_GATEWAY/voice-state-update)                       | someone joined, left, or moved a voice channel                                                                                   |
 | [Voice Server Update](#DOCS_TOPICS_GATEWAY/voice-server-update)                     | guild's voice server was updated                                                                                                 |
 | [Webhooks Update](#DOCS_TOPICS_GATEWAY/webhooks-update)                             | guild channel webhook was created, update, or deleted                                                                            |
+| [Interaction Create](#DOCS_TOPICS_GATEWAY/interaction-create)                       | user used a [Slash Command](#DOCS_INTERACTIONS_SLASH_COMMANDS/)                                                                   |
 
 ### Event Names
 
@@ -652,6 +653,7 @@ The ready event is dispatched when a client has completed the initial handshake
 | guilds           | array of [Unavailable Guild](#DOCS_RESOURCES_GUILD/unavailable-guild-object) objects | the guilds the user is in                                                                                     |
 | session_id       | string                                                                               | used for resuming connections                                                                                 |
 | shard?           | array of two integers (shard_id, num_shards)                                         | the [shard information](#DOCS_TOPICS_GATEWAY/sharding) associated with this session, if sent when identifying |
+| application      | partial [application object](#DOCS_TOPICS_OAUTH2/application-object)                 | contains `id` and `flags`                                                                                     | 
 
 #### Resumed
 
@@ -1215,6 +1217,12 @@ Sent when a guild channel's webhook is created, updated, or deleted.
 | guild_id   | snowflake | id of the guild   |
 | channel_id | snowflake | id of the channel |
 
+### Interactions
+
+### Interaction Create
+
+Sent when a user in a guild uses a [Slash Command](#DOCS_INTERACTIONS_SLASH_COMMANDS/). Inner payload is an [Interaction](#DOCS_INTERACTIONS_SLASH_COMMANDS/interaction).
+
 ## Get Gateway % GET /gateway
 
 > info

diff --git a/docs/topics/OAuth2.md b/docs/topics/OAuth2.md
@@ -9,7 +9,7 @@ The first step in implementing OAuth2 is [registering a developer application](#
 ###### OAuth2 URLs
 
 | URL                                         | Description                                                 |
-| ------------------------------------------- | ----------------------------------------------------------- |
+|---------------------------------------------|-------------------------------------------------------------|
 | https://discord.com/api/oauth2/authorize    | Base authorization URL                                      |
 | https://discord.com/api/oauth2/token        | Token URL                                                   |
 | https://discord.com/api/oauth2/token/revoke | [Token Revocation](https://tools.ietf.org/html/rfc7009) URL |
@@ -21,27 +21,28 @@ The first step in implementing OAuth2 is [registering a developer application](#
 
 These are a list of all the OAuth2 scopes that Discord supports. Scopes that are behind a whitelist cannot be requested unless your application is on said whitelist, and may cause undocumented/error behavior in the OAuth2 flow if you request them from a user.
 
-| Name                       | Description                                                                                                                                           |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| bot                        | for oauth2 bots, this puts the bot in the user's selected guild by default                                                                            |
-| connections                | allows [/users/@me/connections](#DOCS_RESOURCES_USER/get-user-connections) to return linked third-party accounts                                      |
-| email                      | enables [/users/@me](#DOCS_RESOURCES_USER/get-current-user) to return an `email`                                                                      |
-| identify                   | allows [/users/@me](#DOCS_RESOURCES_USER/get-current-user) without `email`                                                                            |
-| guilds                     | allows [/users/@me/guilds](#DOCS_RESOURCES_USER/get-current-user-guilds) to return basic information about all of a user's guilds                     |
-| guilds.join                | allows [/guilds/{guild.id}/members/{user.id}](#DOCS_RESOURCES_GUILD/add-guild-member) to be used for joining users to a guild                         |
-| gdm.join                   | allows your app to [join users to a group dm](#DOCS_RESOURCES_CHANNEL/group-dm-add-recipient)                                                         |
-| messages.read              | for local rpc server api access, this allows you to read messages from all client channels (otherwise restricted to channels/guilds your app creates) |
-| rpc                        | for local rpc server access, this allows you to control a user's local Discord client - whitelist only                                                |
-| rpc.api                    | for local rpc server api access, this allows you to access the API as the local user - whitelist only                                                 |
-| rpc.notifications.read     | for local rpc server api access, this allows you to receive notifications pushed out to the user - whitelist only                                     |
-| webhook.incoming           | this generates a webhook that is returned in the oauth token response for authorization code grants                                                   |
-| applications.builds.upload | allows your app to upload/update builds for a user's applications - whitelist only                                                                    |
-| applications.builds.read   | allows your app to read build data for a user's applications                                                                                          |
-| applications.store.update  | allows your app to read and update store data (SKUs, store listings, achievements, etc.) for a user's applications                                    |
-| applications.entitlements  | allows your app to read entitlements for a user's applications                                                                                        |
-| relationships.read         | allows your app to know a user's friends and implicit relationships - whitelist only                                                                  |
-| activities.read            | allows your app to fetch data from a user's "Now Playing/Recently Played" list - whitelist only                                                       |
-| activities.write           | allows your app to update a user's activity - whitelist only (NOT REQUIRED FOR [GAMESDK ACTIVITY MANAGER](#DOCS_GAME_SDK_ACTIVITIES/))                 |
+| Name                         | Description                                                                                                                                           |
+|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
+| bot                          | for oauth2 bots, this puts the bot in the user's selected guild by default                                                                            |
+| connections                  | allows [/users/@me/connections](#DOCS_RESOURCES_USER/get-user-connections) to return linked third-party accounts                                      |
+| email                        | enables [/users/@me](#DOCS_RESOURCES_USER/get-current-user) to return an `email`                                                                      |
+| identify                     | allows [/users/@me](#DOCS_RESOURCES_USER/get-current-user) without `email`                                                                            |
+| guilds                       | allows [/users/@me/guilds](#DOCS_RESOURCES_USER/get-current-user-guilds) to return basic information about all of a user's guilds                     |
+| guilds.join                  | allows [/guilds/{guild.id}/members/{user.id}](#DOCS_RESOURCES_GUILD/add-guild-member) to be used for joining users to a guild                         |
+| gdm.join                     | allows your app to [join users to a group dm](#DOCS_RESOURCES_CHANNEL/group-dm-add-recipient)                                                         |
+| messages.read                | for local rpc server api access, this allows you to read messages from all client channels (otherwise restricted to channels/guilds your app creates) |
+| rpc                          | for local rpc server access, this allows you to control a user's local Discord client - whitelist only                                                |
+| rpc.api                      | for local rpc server api access, this allows you to access the API as the local user - whitelist only                                                 |
+| rpc.notifications.read       | for local rpc server api access, this allows you to receive notifications pushed out to the user - whitelist only                                     |
+| webhook.incoming             | this generates a webhook that is returned in the oauth token response for authorization code grants                                                   |
+| applications.builds.upload   | allows your app to upload/update builds for a user's applications - whitelist only                                                                    |
+| applications.builds.read     | allows your app to read build data for a user's applications                                                                                          |
+| applications.store.update    | allows your app to read and update store data (SKUs, store listings, achievements, etc.) for a user's applications                                    |
+| applications.entitlements    | allows your app to read entitlements for a user's applications                                                                                        |
+| relationships.read           | allows your app to know a user's friends and implicit relationships - whitelist only                                                                  |
+| activities.read              | allows your app to fetch data from a user's "Now Playing/Recently Played" list - whitelist only                                                       |
+| activities.write             | allows your app to update a user's activity - whitelist only (NOT REQUIRED FOR [GAMESDK ACTIVITY MANAGER](#DOCS_GAME_SDK_ACTIVITIES/))                |
+| applications.commands.update | allows your app to update [Slash Commands](#DOCS_INTERACTIONS_SLASH_COMMANDS/) via this bearer token                                                  |
 
 > info
 > `guilds.join` and `bot` require you to have a bot account linked to your application. Also, in order to add a user to a guild, your bot has to already belong to that guild.
@@ -243,7 +244,7 @@ Bot authorization is a special server-less and callback-less OAuth2 flow that ma
 ###### Bot Auth Parameters
 
 | name                 | description                                                           |
-| -------------------- | --------------------------------------------------------------------- |
+|----------------------|-----------------------------------------------------------------------|
 | client_id            | your app's client id                                                  |
 | scope                | needs to include `bot` for the bot flow                               |
 | permissions          | the [permissions](#DOCS_TOPICS_PERMISSIONS/) you're requesting        |
@@ -365,12 +366,12 @@ Any user that wishes to add your webhook to their channel will need to go throug
 
 ## Get Current Application Information % GET /oauth2/applications/@me
 
-Returns the bot's OAuth2 application info.
+Returns the bot's OAuth2 [application object](#DOCS_TOPICS_OAUTH2/application-object) without `flags`.
 
-###### Response Structure
+###  Application Object
 
 | Field                  | Type                                                       | Description                                                                                                               |
-| ---------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+|------------------------|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
 | id                     | snowflake                                                  | the id of the app                                                                                                         |
 | name                   | string                                                     | the name of the app                                                                                                       |
 | icon                   | ?string                                                    | the icon hash of the app                                                                                                  |
@@ -386,6 +387,7 @@ Returns the bot's OAuth2 application info.
 | primary_sku_id?        | snowflake                                                  | if this application is a game sold on Discord, this field will be the id of the "Game SKU" that is created, if exists     |
 | slug?                  | string                                                     | if this application is a game sold on Discord, this field will be the URL slug that links to the store page               |
 | cover_image?           | string                                                     | if this application is a game sold on Discord, this field will be the hash of the image on store embeds                   |
+| flags                  | int                                                        | the application's public flags                                                                                            |
 
 ###### Example Application Information
 

diff --git a/images/command-with-groups-subcommands-parameters.png b/images/command-with-groups-subcommands-parameters.png
diff --git a/images/command-with-groups-subcommands.png b/images/command-with-groups-subcommands.png
diff --git a/images/command.png b/images/command.png