Skip to content
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

Jump to bottom

Slash Commands and Interactions #2295

Merged
merged 37 commits into from
Dec 15, 2020
Merged

Slash Commands and Interactions #2295

Show file tree
Hide file tree
Changes from 34 commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
30e6cca
Slash Commands and Interactions documentation
msciotti Dec 9, 2020
ab6892a
Nits and TODOs
msciotti Dec 9, 2020
d0479f9
Merge branch 'master' into feature/interactions
msciotti Dec 9, 2020
3792e8b
create, not created
msciotti Dec 10, 2020
452fa08
Fix python make command example
msciotti Dec 10, 2020
0e12e9e
More endpoints
msciotti Dec 10, 2020
f84f72b
groups and subcommands
msciotti Dec 10, 2020
a4e5d78
should be application id
msciotti Dec 10, 2020
261dfc9
interaction create event
msciotti Dec 11, 2020
3928824
Rate limits and maximums
msciotti Dec 11, 2020
36108ce
http verbs
msciotti Dec 11, 2020
0b79af3
Signature validation examples
msciotti Dec 11, 2020
bc58e57
More limits
msciotti Dec 11, 2020
957c592
a better intro
msciotti Dec 14, 2020
50e71ef
swap code samples for sig validation
msciotti Dec 14, 2020
f619909
global -> guild, list -> array
msciotti Dec 14, 2020
101135a
Fix missing id params
msciotti Dec 14, 2020
2c6c4cb
wrong role type
msciotti Dec 14, 2020
54b3ace
NOW the right role type
msciotti Dec 14, 2020
83965c7
PR Fixes and Application Object
msciotti Dec 14, 2020
f9398a7
application on ready
msciotti Dec 14, 2020
a946e0b
headings
msciotti Dec 14, 2020
05bef7d
10s all the way down
msciotti Dec 14, 2020
4eb79ae
grammar and spelling
msciotti Dec 14, 2020
7eaef0d
broken links
msciotti Dec 15, 2020
aaed196
more broken links
msciotti Dec 15, 2020
b3279d9
what even?
msciotti Dec 15, 2020
85e6679
options -> object
msciotti Dec 15, 2020
0810253
one more broken link
msciotti Dec 15, 2020
194aa7e
make things less dangerous
msciotti Dec 15, 2020
c58c4ab
not webhook
msciotti Dec 15, 2020
b50621f
Broken links and spelling
msciotti Dec 15, 2020
4a82475
fix old merge issue in webhook edit
msciotti Dec 15, 2020
11b21c6
subcommand warning
msciotti Dec 15, 2020
5b969d3
PR feedback
msciotti Dec 15, 2020
c39f703
add s
msciotti Dec 15, 2020
9adc416
spelling
msciotti Dec 15, 2020
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
11 changes: 11 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,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
Expand Down
841 changes: 841 additions & 0 deletions docs/interactions/Slash_Commands.md
View file
Open in desktop

Large diffs are not rendered by default.

3 changes: 2 additions & 1 deletion docs/resources/Channel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|----------------------------------------|-------|
Expand All @@ -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

Expand Down
4 changes: 3 additions & 1 deletion docs/resources/Webhook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.
7 changes: 7 additions & 0 deletions docs/topics/Community_Resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/Skillz4Killz/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.
Copy link
Contributor

Choose a reason for hiding this comment

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

The comma after great feels weird.


- [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.
Expand Down
8 changes: 8 additions & 0 deletions docs/topics/Gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
54 changes: 28 additions & 26 deletions docs/topics/OAuth2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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.
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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 |
Expand All @@ -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 |
msciotti marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

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

Is there any specific reason why this isn't called public_flags?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think that all the flags on an application actually are public, as opposed to users where we specifically differentiate. Calling them the public flags covers my butt for now but I can confirm.

Copy link

Choose a reason for hiding this comment

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

It would be useful for future-proofing for a future where bots could be boosted.


###### Example Application Information

Expand Down
Binary file added images/command-with-groups-subcommands-parameters.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/command-with-groups-subcommands.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/command.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.