diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 232219eda5..efb02c8245 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,9 +40,11 @@ Links between docs can be achieved by using a hash symbol (#), plus the markdown Alert boxes are created using a block quote that has one of 'warn', 'danger', 'info', or 'preview' on the first line. For example: + ``` -> warn -> Something that requires warning here +:::warn +Something that requires warning here +::: ``` ![Alert options](static/images/alerts.png) diff --git a/docs/activities/building-an-activity.mdx b/docs/activities/building-an-activity.mdx index 09514c5083..364d6002a5 100644 --- a/docs/activities/building-an-activity.mdx +++ b/docs/activities/building-an-activity.mdx @@ -111,8 +111,9 @@ With our project set up, let's create our app and configure the Activity. Create Enter a name for your app, select a development team, then press **Create**. -> info -> **Development Team Access**
Launching a non-distributed Activity is limited to you or members of the developer team, so if you're collaborating with others during development, create a [developer team](https://discord.com/developers/teams) and set it to the owner when you create the app. +:::info +**Development Team Access**
Launching a non-distributed Activity is limited to you or members of the developer team, so if you're collaborating with others during development, create a [developer team](https://discord.com/developers/teams) and set it to the owner when you create the app. +::: After you create your app, you'll land on the **General Overview** page of the app's settings, where you can update basic information about your app like its description and icon. @@ -158,15 +159,17 @@ In the root of your project, there is an `example.env` file. From the root of yo cp example.env .env ``` -> warn -> **Secure Your Secrets**
Your `DISCORD_CLIENT_SECRET` and `DISCORD_BOT_TOKEN` are *highly* sensitive secrets. Never share either secrets or check them into any kind of version control. +:::warn +**Secure Your Secrets**
Your `DISCORD_CLIENT_SECRET` and `DISCORD_BOT_TOKEN` are *highly* sensitive secrets. Never share either secrets or check them into any kind of version control. +::: Back in your app's settings, click on **OAuth2** on the sidebar: 1. **Client ID**: Copy the value for Client ID and add it to your `.env` file as **`VITE_CLIENT_ID`**. This is the public ID that Discord associates with your app, and is almost always the same as your App ID. 2. **Client Secret**: Copy the value for Client Secret and add it to your `.env` as **`DISCORD_CLIENT_SECRET`**. This is a private, sensitive identifier that your app will use to grant an OAuth2 `access_token`, and should never be shared or checked into version control. -> info -> **Why is there a VITE_ prefix before our Client ID?**
Prefixing the `CLIENT_ID` environment variable with `VITE_` makes it accessible to our client-side code. This security measure ensures that only the variables you intend to be accessible in the browser are available, and all other environment variables remain private. You can read details in the [Vite documentation](https://vitejs.dev/guide/env-and-mode). +:::info +**Why is there a VITE_ prefix before our Client ID?**
Prefixing the `CLIENT_ID` environment variable with `VITE_` makes it accessible to our client-side code. This security measure ensures that only the variables you intend to be accessible in the browser are available, and all other environment variables remain private. You can read details in the [Vite documentation](https://vitejs.dev/guide/env-and-mode). +::: @@ -181,8 +184,9 @@ With our project and app set up, we're going to install and configure the [Embed The Embedded App SDK is a first-party SDK that handles the communication between Discord and your Activity with [commands](/docs/developer-tools/embedded-app-sdk#sdk-commands) to interact with the Discord client (like fetching information about the channel) and [events](/docs/developer-tools/embedded-app-sdk#sdk-events) to listen for user actions and changes in state (like when a user starts or stops speaking). -> info -> The events and commands available in the Embedded App SDK are a subset of the [RPC API](/docs/topics/rpc) ones, so referencing the RPC documentation can be helpful to understand what's happening under the hood when developing Activities. +:::info +The events and commands available in the Embedded App SDK are a subset of the [RPC API](/docs/topics/rpc) ones, so referencing the RPC documentation can be helpful to understand what's happening under the hood when developing Activities. +::: ### Install the SDK @@ -234,8 +238,9 @@ document.querySelector('#app').innerHTML = ` -> warn -> **Time to leave your browser behind**
Once you add the SDK to your app, you will **not** be able to view your app inside your web browser. In the next step, we will run your Activity inside of Discord. In the next step, we will go over how to view your app in Discord. +:::warn +**Time to leave your browser behind**
Once you add the SDK to your app, you will **not** be able to view your app inside your web browser. In the next step, we will run your Activity inside of Discord. In the next step, we will go over how to view your app in Discord. +::: @@ -330,8 +335,9 @@ Clicking on your app will launch your locally running app from inside Discord! ![Running your activity](images/activities/start-activity.png) -> info -> **Customizing your Activity**
If you'd like to set images for your Activity, you can learn how to do that [here](/docs/activities/development-guides#setting-up-activity-metadata). +:::info +**Customizing your Activity**
If you'd like to set images for your Activity, you can learn how to do that [here](/docs/activities/development-guides#setting-up-activity-metadata). +::: We're looking pretty good so far, but we haven't wired up any Discord functionality yet. Let's do that next. @@ -441,8 +447,9 @@ We can now run our server and client-side apps in separate terminal windows. You Before we call your backend activity server, we need to be aware of the Discord proxy and understand how to avoid any Content Security Policy (CSP) issues. -> info -> For this tutorial, we are going to prefix the API call to `/api/token/` with `/.proxy`, but you can also use the SDK's `patchUrlMappings()` method to automatically prefix calls to your external resources for the proxy. +:::info +For this tutorial, we are going to prefix the API call to `/api/token/` with `/.proxy`, but you can also use the SDK's `patchUrlMappings()` method to automatically prefix calls to your external resources for the proxy. +::: Learn more about this topic in the guides for [Constructing a Full URL](/docs/activities/development-guides#construct-a-full-url) and [Using External Resources](/docs/activities/development-guides#using-external-resources). @@ -450,9 +457,11 @@ Learn more about this topic in the guides for [Constructing a Full URL](/docs/ac We're almost there! Now, we need our client application to communicate with our server so we can start the OAuth process and get an access token. -> info -> **What is vite.config.js?**
-> To allow our frontend app to call our Express server, Vite requires us to set up a proxy for `/api/*` to our backend server, which is running on port 3001. In their docs, you can learn more about [Vite](https://vitejs.dev/). +:::info +**What is vite.config.js?** + +To allow our frontend app to call our Express server, Vite requires us to set up a proxy for `/api/*` to our backend server, which is running on port 3001. In their docs, you can learn more about [Vite](https://vitejs.dev/). +::: @@ -531,9 +540,11 @@ Now if we relaunch our app, we'll be prompted to authorize with Discord using th ![Prompt to authorize Activity](images/activities/tutorial-auth.png) -> warn -> **Safe storage of tokens**
-> Access tokens and refresh tokens are powerful, and should be treated similarly to passwords or other highly-sensitive data. Store both types of tokens securely and in an encrypted manner. +:::warn +**Safe storage of tokens** + +Access tokens and refresh tokens are powerful, and should be treated similarly to passwords or other highly-sensitive data. Store both types of tokens securely and in an encrypted manner. +::: @@ -612,8 +623,9 @@ In the following code block, we will: 2. Iterate over each guild to find the guild we are in based on the `guildId` defined in discordSdk 3. Create a new HTML image element with the guild avatar and append it to our frontend -> info -> In this example, we use a pure `fetch` request to make the API call, but you can us one of the JavaScript [community-built libraries](/docs/developer-tools/community-resources) if you prefer. +:::info +In this example, we use a pure `fetch` request to make the API call, but you can us one of the JavaScript [community-built libraries](/docs/developer-tools/community-resources) if you prefer. +::: diff --git a/docs/activities/design-patterns.mdx b/docs/activities/design-patterns.mdx index 519397e11c..3bec4926e3 100644 --- a/docs/activities/design-patterns.mdx +++ b/docs/activities/design-patterns.mdx @@ -114,8 +114,9 @@ Discord is a social platform where users talk to each other. Sharing and invites ### Monetization Considerations -> preview -> Monetization in Activities will be available soon. Keep the following considerations in mind as you design your Activity. +:::preview +Monetization in Activities will be available soon. Keep the following considerations in mind as you design your Activity. +::: - Avoid prohibitive gates in front of participation (e.g. login wall / paywall), especially early in the user journey. - Avoid monetized unlocks that give unfair advantage to other non-paying players or users (i.e. "pay to win"). diff --git a/docs/activities/development-guides.mdx b/docs/activities/development-guides.mdx index 9a378c06d6..6c7127a91f 100644 --- a/docs/activities/development-guides.mdx +++ b/docs/activities/development-guides.mdx @@ -154,8 +154,9 @@ Although it is possible to test your application locally, we recommend developin 4. Locally, spin up your web server. 5. Install and run a tunnel solution, such as [cloudflared](https://github.com/cloudflare/cloudflared#installing-cloudflared). You will point it to your local web server. -> info -> Your web server can be HTTP and your network tunnel can upgrade the connection to HTTPS. +:::info +Your web server can be HTTP and your network tunnel can upgrade the connection to HTTPS. +::: If using cloudflared, you will run the following command, replace `3000` with your web server's port. @@ -174,8 +175,9 @@ In the Discord Developer Portal, update the Application URL mapping for `/` url ![Configuring your URL Mapping](images/activities/url-mapping-tutorial.png) -> warn -> If you do not own the URL that you are using to host the application (i.e. ngrok's free tier), someone else could claim that domain and host a malicious site in its place. Please be aware of these risks, and if you have to use a domain you do not own, be sure to reset your URL mapping when you are done using the tunnel. +:::warn +If you do not own the URL that you are using to host the application (i.e. ngrok's free tier), someone else could claim that domain and host a malicious site in its place. Please be aware of these risks, and if you have to use a domain you do not own, be sure to reset your URL mapping when you are done using the tunnel. +::: Follow the instructions for [Launching your Application from the Discord Client](/docs/activities/development-guides#launch-your-application-from-the-discord-client). Application URL Override should not be enabled. @@ -588,8 +590,9 @@ discordSdk.subscribe('THERMAL_STATE_UPDATE', handleThermalStateUpdate); Discord will publish the current thermal state upon event subscription, and it will also publish any thermal state changes that happen afterward. -> info -> On Android devices, the thermal state updates will only be available on Android 10 and higher. +:::info +On Android devices, the thermal state updates will only be available on Android 10 and higher. +::: --- @@ -747,8 +750,9 @@ async function setupApp() { } ``` -> info -> Note: `patchUrlMappings` is modifying your browser's `fetch`, `WebSocket`, and `XMLHttpRequest.prototype.open` global variables. Depending on the library, you may see side effects from using this helper function. It should be used only when necessary. +:::info +Note: `patchUrlMappings` is modifying your browser's `fetch`, `WebSocket`, and `XMLHttpRequest.prototype.open` global variables. Depending on the library, you may see side effects from using this helper function. It should be used only when necessary. +::: --- @@ -1016,8 +1020,9 @@ Once you're satisfied with your changes you can click on the copy icon on the ro 1. Click on the trash icon on the row of the link you're trying to delete. 2. You'll have a confirm dialog pop up. -> warn -> Deleting is irreversible and immediate. Ensure that your link isn't in active use before deleting and/or that your activity gracefully handles any click-throughs from the link. +:::warn +Deleting is irreversible and immediate. Ensure that your link isn't in active use before deleting and/or that your activity gracefully handles any click-throughs from the link. +::: #### Best Practices @@ -1109,8 +1114,9 @@ To update your app's metadata in the Discord Developer Portal, navigate to the ` - Leaving this field empty defaults to `Unlimited participants`. - Max Participants is also displayed under the name in the 2-up view. -> info -> An app can have a different application name and avatar from the application's bot username and avatar. Both sets of metadata are public-facing and may be visible in various situations when a user interacts with your app. You can view your bot's username on the `Settings -> Bot` tab. +:::info +An app can have a different application name and avatar from the application's bot username and avatar. Both sets of metadata are public-facing and may be visible in various situations when a user interacts with your app. You can view your bot's username on the `Settings -> Bot` tab. +::: --- diff --git a/docs/activities/how-activities-work.md b/docs/activities/how-activities-work.md index 5a3aab985b..ca894dffe1 100644 --- a/docs/activities/how-activities-work.md +++ b/docs/activities/how-activities-work.md @@ -19,8 +19,9 @@ This SDK is intended for use by a single-page application. We recognize develope ## Sample Code and Activity Lifecycle Diagram -> info -> Below is a minimal example of setting up the SDK. Please see our [Sample Projects](/docs/activities/overview#sample-projects) for more complete sample applications. +:::info +Below is a minimal example of setting up the SDK. Please see our [Sample Projects](/docs/activities/overview#sample-projects) for more complete sample applications. +::: ```javascript import {DiscordSDK} from '@discord/embedded-app-sdk'; diff --git a/docs/change-log/2022-06-29-changes-to-bot-permissions-for-interactions-and-webhooks.md b/docs/change-log/2022-06-29-changes-to-bot-permissions-for-interactions-and-webhooks.md index b4560f5c49..5db2faefd1 100644 --- a/docs/change-log/2022-06-29-changes-to-bot-permissions-for-interactions-and-webhooks.md +++ b/docs/change-log/2022-06-29-changes-to-bot-permissions-for-interactions-and-webhooks.md @@ -6,8 +6,9 @@ breaking: true #### Upcoming Changes -> warn -> `MENTION_EVERYONE`, `SEND_TTS_MESSAGES` and `USE_EXTERNAL_EMOJIS` are the only permissions that will be affected by this change. In a previous version of this changelog, it was indicated that `ATTACH_FILES` and `EMBED_LINKS` would be affected but this is no longer the case. +:::warn +`MENTION_EVERYONE`, `SEND_TTS_MESSAGES` and `USE_EXTERNAL_EMOJIS` are the only permissions that will be affected by this change. In a previous version of this changelog, it was indicated that `ATTACH_FILES` and `EMBED_LINKS` would be affected but this is no longer the case. +::: Starting **August 3, 2022**, the way some of a bot's `MENTION_EVERYONE`, `SEND_TTS_MESSAGES` and `USE_EXTERNAL_EMOJIS` [permissions](/docs/topics/permissions#permissions) are calculated is changing in two cases: diff --git a/docs/change-log/2022-08-09-session-specific-gateway-resume-urls.md b/docs/change-log/2022-08-09-session-specific-gateway-resume-urls.md index a136309b08..372e85d8ed 100644 --- a/docs/change-log/2022-08-09-session-specific-gateway-resume-urls.md +++ b/docs/change-log/2022-08-09-session-specific-gateway-resume-urls.md @@ -3,8 +3,9 @@ title: "Session-specific Gateway Resume URLs" date: "2022-08-09" --- -> warn -> Starting on **September 12, 2022**, apps that aren’t using the new `resume_gateway_url` field to resume gateway sessions will be disconnected significantly faster than normal. +:::warn +Starting on **September 12, 2022**, apps that aren’t using the new `resume_gateway_url` field to resume gateway sessions will be disconnected significantly faster than normal. +::: A new `resume_gateway_url` field has been added to the [Ready](/docs/events/gateway-events#ready) gateway event to support session-specific gateway connections. The value of `resume_gateway_url` is a session-specific URL that should be used when resuming the gateway session after a disconnect. Previously, `wss://gateway.discord.gg` was used to connect *and* resume sessions, but should now only be used during the connection. diff --git a/docs/change-log/2022-11-17-upcoming-application-command-permission-changes.md b/docs/change-log/2022-11-17-upcoming-application-command-permission-changes.md index 44ac68053a..13d21a536f 100644 --- a/docs/change-log/2022-11-17-upcoming-application-command-permission-changes.md +++ b/docs/change-log/2022-11-17-upcoming-application-command-permission-changes.md @@ -8,15 +8,17 @@ Based on feedback, we’re updating permissions for [application commands](/docs Server admins can begin to opt-in to the command permission changes outlined here on a per-server basis **starting on December 16, 2022**. However, changes will not be applied to all servers **until late January or early February**. -> info -> Current permissions behavior is documented in [the application commands documentation](/docs/interactions/application-commands#permissions) and in [the changelog for the previous permissions update](/docs/change-log#updated-command-permissions) +:::info +Current permissions behavior is documented in [the application commands documentation](/docs/interactions/application-commands#permissions) and in [the changelog for the previous permissions update](/docs/change-log#updated-command-permissions) +::: These changes are focused on how configured permissions are used by Discord clients, so most apps will be unaffected. However, if your app uses the [Update Permissions endpoint](/docs/interactions/application-commands#edit-application-command-permissions) (`PUT /applications//guilds//commands//permissions`), you may need to make updates and should read these changes carefully. #### Types of command permission configurations -> info -> The following information isn’t changing, but it’s helpful context to understand the changes. +:::info +The following information isn’t changing, but it’s helpful context to understand the changes. +::: Discord’s clients determine whether a user can see or invoke a command based on three different permission configurations: @@ -102,8 +104,9 @@ else: # Use new permissions behaviors when interacting with endpoint ``` -> info -> If you don’t have access to guild features already through Gateway events, you can fetch that information using the [`GET /guilds/` endpoint](/docs/resources/guild#get-guild). +:::info +If you don’t have access to guild features already through Gateway events, you can fetch that information using the [`GET /guilds/` endpoint](/docs/resources/guild#get-guild). +::: **2. Modify the behavior based on your use case** diff --git a/docs/change-log/2022-12-12-add-application-connections-metadata-and-linked-roles.md b/docs/change-log/2022-12-12-add-application-connections-metadata-and-linked-roles.md index 07518d450b..d1bdb0560d 100644 --- a/docs/change-log/2022-12-12-add-application-connections-metadata-and-linked-roles.md +++ b/docs/change-log/2022-12-12-add-application-connections-metadata-and-linked-roles.md @@ -11,5 +11,6 @@ Introducing [linked roles](https://discord.com/blog/connected-accounts-functiona * New [`role_connections.write`](/docs/topics/oauth2#shared-resources-oauth2-scopes) OAuth2 scope required to authenticate the below requests. * Endpoints to [retrieve](/docs/resources/user#get-current-user-application-role-connection) (`GET /users/@me/applications/{application.id}/role-connection`) and [update](/docs/resources/user#update-current-user-application-role-connection) (`PUT /users/@me/applications/{application.id}/role-connection`) a user's role connections, both of which return an [application role connection](/docs/resources/user#application-role-connection-object) object. -> info -> For a quick rundown on how to get started using linked roles, refer to the [tutorial](/docs/tutorials/configuring-app-metadata-for-linked-roles). +:::info +For a quick rundown on how to get started using linked roles, refer to the [tutorial](/docs/tutorials/configuring-app-metadata-for-linked-roles). +::: diff --git a/docs/change-log/2023-05-03-unique-usernames-on-discord.md b/docs/change-log/2023-05-03-unique-usernames-on-discord.md index 2ed79e2567..38b52d6761 100644 --- a/docs/change-log/2023-05-03-unique-usernames-on-discord.md +++ b/docs/change-log/2023-05-03-unique-usernames-on-discord.md @@ -3,8 +3,9 @@ title: "Unique usernames on Discord" date: "2023-05-03" --- -> warn -> Bot users will stay on the legacy username system for now. More details can be found on the [Developer Help Center article](https://dis.gd/app-usernames). +:::warn +Bot users will stay on the legacy username system for now. More details can be found on the [Developer Help Center article](https://dis.gd/app-usernames). +::: Discord’s username system is changing. Discriminators are being removed and new, unique usernames and display names are being introduced. You can read more details about how changes to the username system affects non-bot users in the [general Help Center article](https://dis.gd/usernames). To learn how it impacts bot users specifically, you can read the [Developer Help Center article](https://dis.gd/app-usernames). diff --git a/docs/change-log/2023-08-02-public-preview-of-openapi-3.1-specification.md b/docs/change-log/2023-08-02-public-preview-of-openapi-3.1-specification.md index 1297b32148..20190f5a24 100644 --- a/docs/change-log/2023-08-02-public-preview-of-openapi-3.1-specification.md +++ b/docs/change-log/2023-08-02-public-preview-of-openapi-3.1-specification.md @@ -5,7 +5,8 @@ date: "2023-08-02" We're introducing an [OpenAPI 3.1 spec](https://github.com/discord/discord-api-spec) in public preview to make it easier and more reliable to develop with the HTTP API. While our current developer documentation requires manual reviews and updates, the OpenAPI spec is generated from the source code which means it better reflects the nooks, crannies, and nuances of the Discord API. -> warn -> The public preview of the OpenAPI spec is subject to breaking changes without advance notice, and should not be used within production environments. If you see something that looks incorrect or can be improved, you can [open an issue](https://github.com/discord/discord-api-spec/issues). +:::warn +The public preview of the OpenAPI spec is subject to breaking changes without advance notice, and should not be used within production environments. If you see something that looks incorrect or can be improved, you can [open an issue](https://github.com/discord/discord-api-spec/issues). +::: The public spec can be found in the new [`discord-api-spec` repository on GitHub](https://github.com/discord/discord-api-spec). diff --git a/docs/change-log/2023-10-19-premium-app-subscriptions-now-available-in-the-eu-and-uk.md b/docs/change-log/2023-10-19-premium-app-subscriptions-now-available-in-the-eu-and-uk.md index 291bc67671..90dd558764 100644 --- a/docs/change-log/2023-10-19-premium-app-subscriptions-now-available-in-the-eu-and-uk.md +++ b/docs/change-log/2023-10-19-premium-app-subscriptions-now-available-in-the-eu-and-uk.md @@ -7,7 +7,8 @@ topics: Starting today, eligible developers based in EU and UK can now monetize their verified apps with App Subscriptions. [App Subscriptions](/docs/monetization/overview) let you to charge your users for premium functionality with a recurring, monthly subscription. -> info -> New features for Premium App Subscriptions are documented in the [App Subscriptions overview](/docs/monetization/overview) and in [the changelog for the previous App Subscriptions release](/docs/change-log#premium-app-subscriptions-available-in-the-us). +:::info +New features for Premium App Subscriptions are documented in the [App Subscriptions overview](/docs/monetization/overview) and in [the changelog for the previous App Subscriptions release](/docs/change-log#premium-app-subscriptions-available-in-the-us). +::: To learn more about eligibility details and how to enable monetization for your app, check out the [Monetization Overview](/docs/monetization/overview). diff --git a/docs/change-log/2023-12-15-clarification-on-permission-splits-for-expressions-and-events.md b/docs/change-log/2023-12-15-clarification-on-permission-splits-for-expressions-and-events.md index 79bc40e0b6..f73e002f4f 100644 --- a/docs/change-log/2023-12-15-clarification-on-permission-splits-for-expressions-and-events.md +++ b/docs/change-log/2023-12-15-clarification-on-permission-splits-for-expressions-and-events.md @@ -3,8 +3,9 @@ title: "Clarification on Permission Splits for Expressions and Events" date: "2023-12-15" --- -> info -> The existing behavior for `MANAGE_GUILD_EXPRESSIONS` and `MANAGE_EVENTS` will **not be changing**. These permissions will continue to allow your bot users to create, update and delete expressions/events. No action will be needed if you plan to continue using these permissions. +:::info +The existing behavior for `MANAGE_GUILD_EXPRESSIONS` and `MANAGE_EVENTS` will **not be changing**. These permissions will continue to allow your bot users to create, update and delete expressions/events. No action will be needed if you plan to continue using these permissions. +::: To support added controls for expressions and events, new [permissions](/docs/topics/permissions#permissions) were added for users and roles in July 2023: @@ -13,5 +14,6 @@ To support added controls for expressions and events, new [permissions](/docs/to These allow for creating new expressions and events, as well as editing and deleting those created by the current user. -> warn -> These were rolled out in July 2023 to users and roles and have been added to our developer documentation but **are not yet available to app developers**. We will share an update here when these new permissions are available in your apps. +:::warn +These were rolled out in July 2023 to users and roles and have been added to our developer documentation but **are not yet available to app developers**. We will share an update here when these new permissions are available in your apps. +::: diff --git a/docs/change-log/2024-06-17-premium-apps-new-premium-button-style-deep-linking-url-schemes.md b/docs/change-log/2024-06-17-premium-apps-new-premium-button-style-deep-linking-url-schemes.md index d56b8f4c94..ac00de8322 100644 --- a/docs/change-log/2024-06-17-premium-apps-new-premium-button-style-deep-linking-url-schemes.md +++ b/docs/change-log/2024-06-17-premium-apps-new-premium-button-style-deep-linking-url-schemes.md @@ -9,8 +9,9 @@ Introduces a new `premium` [button style](/docs/interactions/message-components# Learn more about using [button components with interactions](/docs/interactions/message-components#buttons). -> warn -> This change deprecates Interaction Response Type 10 +:::warn +This change deprecates Interaction Response Type 10 +::: The `PREMIUM_REQUIRED (10)` interaction response type is now deprecated in favor of using custom premium buttons. This will continue to function but may be eventually unsupported. It is recommended to migrate your bots to use the more flexible [premium button component](/docs/interactions/message-components#button-object-button-styles). diff --git a/docs/change-log/2024-07-25-supported-activity-types-for-set-activity.md b/docs/change-log/2024-07-25-supported-activity-types-for-set-activity.md index 0cf982df94..e56f9c1faa 100644 --- a/docs/change-log/2024-07-25-supported-activity-types-for-set-activity.md +++ b/docs/change-log/2024-07-25-supported-activity-types-for-set-activity.md @@ -5,5 +5,6 @@ date: "2024-07-25" The [`SET_ACTIVITY` RPC command](/docs/topics/rpc#setactivity) has been updated to support 3 additional [activity types](/docs/events/gateway-events#activity-object-activity-types): Listening (`2`), Watching (`3`), and Competing (`5`). Previously, it only accepted Playing (`0`). -> warn -> The [Game SDK](/docs/developer-tools/game-sdk#activities) has not been updated to support setting [`ActivityType`](/docs/developer-tools/game-sdk#activitytype-enum), and is still limited to read-only (to handle events that you receive from Discord). +:::warn +The [Game SDK](/docs/developer-tools/game-sdk#activities) has not been updated to support setting [`ActivityType`](/docs/developer-tools/game-sdk#activitytype-enum), and is still limited to read-only (to handle events that you receive from Discord). +::: diff --git a/docs/change-log/2024-08-13-voice-encryption-modes.md b/docs/change-log/2024-08-13-voice-encryption-modes.md index d4472c154d..27e13b6c60 100644 --- a/docs/change-log/2024-08-13-voice-encryption-modes.md +++ b/docs/change-log/2024-08-13-voice-encryption-modes.md @@ -7,5 +7,6 @@ topics: Added documentation for voice [encryption modes](/docs/topics/voice-connections#transport-encryption-modes) `aead_aes256_gcm_rtpsize` and `aead_xchacha20_poly1305_rtpsize` while announcing the deprecation of all `xsalsa20_poly1305*` variants and `aead_aes256_gcm`. Deprecated encryption modes will be discontinued as of November 18th, 2024. -> danger -> Deprecated encryption modes will be discontinued as of November 18th, 2024. +:::danger +Deprecated encryption modes will be discontinued as of November 18th, 2024. +::: diff --git a/docs/change-log/2024-08-13-voice-gateway-version-8-and-deprecation-of-versions-older-than-4.md b/docs/change-log/2024-08-13-voice-gateway-version-8-and-deprecation-of-versions-older-than-4.md index 1409c7d0c2..4e1fbd40f4 100644 --- a/docs/change-log/2024-08-13-voice-gateway-version-8-and-deprecation-of-versions-older-than-4.md +++ b/docs/change-log/2024-08-13-voice-gateway-version-8-and-deprecation-of-versions-older-than-4.md @@ -11,5 +11,6 @@ We are officially deprecating some very old voice gateway versions (> 7 years ag * The voice gateway now supports a resume which re-sends lost messages. Use voice gateway version 8 and refer to [Buffered Resume](/docs/topics/voice-connections#buffered-resume). * We have removed the default option for voice gateway version. Once this is deprecated, you must pass a voice gateway version. -> danger -> You will be required to pass a voice gateway version and deprecated voice gateway versions will be discontinued as of November 18th, 2024. See [Voice Gateway Versioning](/docs/topics/voice-connections#voice-gateway-versioning) for futher details. +:::danger +You will be required to pass a voice gateway version and deprecated voice gateway versions will be discontinued as of November 18th, 2024. See [Voice Gateway Versioning](/docs/topics/voice-connections#voice-gateway-versioning) for futher details. +::: diff --git a/docs/change-log/2024-08-28-subscription-api-and-entitlement-migration.md b/docs/change-log/2024-08-28-subscription-api-and-entitlement-migration.md index dc6939619e..87d237801d 100644 --- a/docs/change-log/2024-08-28-subscription-api-and-entitlement-migration.md +++ b/docs/change-log/2024-08-28-subscription-api-and-entitlement-migration.md @@ -6,13 +6,15 @@ topics: breaking: true --- -> info -> Updates to this Change Log entry was published on **October 7, 2024** to reflect up-to-date information. See the [new Change Log entry](/docs/change-log#updates-to-entitlement-migration-guide) for details on updates. +:::info +Updates to this Change Log entry was published on **October 7, 2024** to reflect up-to-date information. See the [new Change Log entry](/docs/change-log#updates-to-entitlement-migration-guide) for details on updates. +::: We are migrating our entitlement system to a new behavior where entitlements will not end until explicitly canceled, representing a breaking change for subscription management. We are introducing a [Subscription API](/docs/resources/subscription) and [Subscription Events](/docs/events/gateway-events#subscriptions) to allow handling subscription-related events. -> warn -> This change will be rolled out to all existing applications that have entitlements for user and guild subscription SKUs, starting on October 1, 2024. +:::warn +This change will be rolled out to all existing applications that have entitlements for user and guild subscription SKUs, starting on October 1, 2024. +::: #### Entitlement Migration Details @@ -44,8 +46,9 @@ As part of these changes, we've updated the documentation for Premium Apps. Starting on **October 1, 2024**, we will be migrating our existing entitlement system to a new behavior where **entitlements do not expire until explicitly canceled**. This migration guide outlines the changes and impacts of this migration on developers and guides how to manage these changes effectively. -> warn -> With this update, entitlements for subscription SKUs will no longer emit events when a new subscription billing period begins. If you need to know when a subscription has been renewed, use the new [Subscription API](/docs/resources/subscription) and related [Subscription Gateway Events](/docs/events/gateway-events#subscriptions). +:::warn +With this update, entitlements for subscription SKUs will no longer emit events when a new subscription billing period begins. If you need to know when a subscription has been renewed, use the new [Subscription API](/docs/resources/subscription) and related [Subscription Gateway Events](/docs/events/gateway-events#subscriptions). +::: ### Current System diff --git a/docs/change-log/2024-10-25-event-webhooks.md b/docs/change-log/2024-10-25-event-webhooks.md index d4c001b351..0ca8c6f5b6 100644 --- a/docs/change-log/2024-10-25-event-webhooks.md +++ b/docs/change-log/2024-10-25-event-webhooks.md @@ -9,8 +9,10 @@ topics: You can now subscribe to a limited number of HTTP-based outgoing [webhook events](/docs/events/webhook-events#event-types) after [configuring a webhook events URL](/docs/events/webhook-events#configuring-a-webhook-events-url). Currently, 3 events are available: `APPLICATION_AUTHORIZED`, `ENTITLEMENT_CREATE`, and `QUEST_USER_ENROLLMENT`. Read the [webhook events](/docs/events/webhook-events) documentation for details on subscribing and using webhook events. -> info -> When developing [user-installable apps](/docs/resources/application#user-context), [Application Authorized](/docs/events/webhook-events#application-authorized) (which is not available via [the Gateway](/docs/events/gateway)) is useful to receive events when your app was installed to a user or server. +:::info +When developing [user-installable apps](/docs/resources/application#user-context), [Application Authorized](/docs/events/webhook-events#application-authorized) (which is not available via [the Gateway](/docs/events/gateway)) is useful to receive events when your app was installed to a user or server. +::: -> warn -> `ENTITLEMENT_CREATE` is the only monetization-related event available using webhook events, so you should still use the Gateway for [entitlement-related events](/docs/events/gateway-events#entitlements). Other monetization-related events will be supported via webhook events soon. \ No newline at end of file +:::warn +`ENTITLEMENT_CREATE` is the only monetization-related event available using webhook events, so you should still use the Gateway for [entitlement-related events](/docs/events/gateway-events#entitlements). Other monetization-related events will be supported via webhook events soon. +::: \ No newline at end of file diff --git a/docs/developer-tools/community-resources.mdx b/docs/developer-tools/community-resources.mdx index 2160307f24..4990bea2aa 100644 --- a/docs/developer-tools/community-resources.mdx +++ b/docs/developer-tools/community-resources.mdx @@ -65,8 +65,9 @@ Discord does not maintain official SDKs. The following table is an inexhaustive ## OpenAPI Specification -> warn -> The OpenAPI spec is currently in public preview and **is subject to breaking changes** +:::warn +The OpenAPI spec is currently in public preview and **is subject to breaking changes** +::: The public preview of the [Discord HTTP API specification](https://github.com/discord/discord-api-spec) provides a standard [OpenAPI 3.1 spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) for the HTTP API. diff --git a/docs/developer-tools/embedded-app-sdk.mdx b/docs/developer-tools/embedded-app-sdk.mdx index 85192b8c41..afde3d6a37 100644 --- a/docs/developer-tools/embedded-app-sdk.mdx +++ b/docs/developer-tools/embedded-app-sdk.mdx @@ -1056,8 +1056,9 @@ No scopes required ### ENTITLEMENT_CREATE -> preview -> Coming soon! Not available during Developer Preview +:::preview + Coming soon! Not available during Developer Preview +::: ## SDK Interfaces @@ -1408,8 +1409,9 @@ No scopes required #### OpenExternalLinkResponse -> warn -> `{ opened: null }` is returned on Discord clients before December 2024 that do not report the open link result. +:::warn +`{ opened: null }` is returned on Discord clients before December 2024 that do not report the open link result. +::: | Property | Type | |----------|-----------------| diff --git a/docs/developer-tools/game-sdk.mdx b/docs/developer-tools/game-sdk.mdx index a20a23885b..531d799982 100644 --- a/docs/developer-tools/game-sdk.mdx +++ b/docs/developer-tools/game-sdk.mdx @@ -2,8 +2,9 @@ # Game SDK -> warn -> **The Game SDK has been archived.**
We recommend using the [Discord Social SDK](/docs/discord-social-sdk/overview) for new projects.
Existing projects using the Game SDK will continue to work, but we encourage you to migrate to the [Discord Social SDK](/docs/discord-social-sdk/overview) for new features and updates. +:::warn +**The Game SDK has been archived.**
We recommend using the [Discord Social SDK](/docs/discord-social-sdk/overview) for new projects.
Existing projects using the Game SDK will continue to work, but we encourage you to migrate to the [Discord Social SDK](/docs/discord-social-sdk/overview) for new features and updates. +::: Welcome to the documentation for the Discord Game SDK! We're glad you made it. The Game SDK helps you develop your 3rd party game or app, and integrate it with Discord. @@ -32,8 +33,9 @@ Head over to our [developer site](https://discord.com/developers/) and create an Now that your team is created, you'll want to make an application. To do so, click on "Applications" at the top of the page and create an application. Make sure you pick your newly-created team in the `Team` dropdown. You want your team to own the application! Now that your app is made, let's dive into some more setup. -> warn -> If you're integrating our SDK into an already-released game, there's a good chance that we may _already have_ an application in our database for your game! Reach out to our [Dev Support](https://dis.gd/devsupport) to learn more +:::warn +If you're integrating our SDK into an already-released game, there's a good chance that we may _already have_ an application in our database for your game! Reach out to our [Dev Support](https://dis.gd/devsupport) to learn more +::: First, we'll need to set an OAuth2 redirect URL. You can add `http://127.0.0.1` in there for now; this powers some behind-the-scenes stuff you don't need to worry about. @@ -328,8 +330,9 @@ We know that getting a test build of a game on two separate machines can be both -> info -> Value from environment variable `DISCORD_INSTANCE_ID` +:::info +Value from environment variable `DISCORD_INSTANCE_ID` +::: By using system environment variables, you can tell the SDK in a certain game client to connect to a specific Discord client. Here's how it works: @@ -356,8 +359,9 @@ var discord = new Discord(applicationId, Discord.CreateFlags.Default); This will set the environment variable only within the context of the running process, so don't worry about messing up global stuff. -> danger -> If you test with this, make sure to remove this code before pushing a production build. It will interfere with the way that Discord launches games for users. +:::danger +If you test with this, make sure to remove this code before pushing a production build. It will interfere with the way that Discord launches games for users. +::: @@ -471,8 +475,9 @@ var discord = new Discord(53908232506183680, (UInt64)Discord.CreateFlags.Default Destroys the instance. Wave goodbye, Nelly! You monster. In C# land, this is `Dispose()`. -> info -> The C++ binding does not include a `destroy()` method, as the destructor for the Core does the work for you. +:::info +The C++ binding does not include a `destroy()` method, as the destructor for the Core does the work for you. +::: Returns `void`. @@ -565,8 +570,9 @@ var overlayManager = discord.GetOverlayManager(); ## Activities -> info -> Looking to build a game inside of Discord? Check out the (other) [Activities](/docs/activities/overview) and the [Embedded SDK](/docs/developer-tools/embedded-app-sdk) documentation. +:::info +Looking to build a game inside of Discord? Check out the (other) [Activities](/docs/activities/overview) and the [Embedded SDK](/docs/developer-tools/embedded-app-sdk) documentation. +::: Looking to integrate Rich Presence into your game? No need to manage multiple SDKs—this one does all that awesome stuff, too! Delight your players with the ability to post game invites in chat and party up directly from Discord. Surface interesting live game data in their profile for their friends, encouraging them to group up and play together. @@ -735,8 +741,9 @@ activityManager.RegisterSteam(1938123); Sets a user's presence in Discord to a new activity. This has a rate limit of 5 updates per 20 seconds. -> info -> It is possible for users to hide their presence on Discord (User Settings -> Game Activity). Presence set through this SDK may not be visible when this setting is toggled off. +:::info +It is possible for users to hide their presence on Discord (User Settings -> Game Activity). Presence set through this SDK may not be visible when this setting is toggled off. +::: Returns a `Discord.Result` via callback. @@ -1136,8 +1143,9 @@ activityManager.UpdateActivity(activity, (result) => ## Overlay -> warn -> The overlay is only supported on Windows for DirectX or OpenGL games. Linux, Mac, and games using Vulkan are not supported. [Click here for more info.](https://support.discord.com/hc/en-us/articles/217659737-Games-Overlay-101) +:::warn +The overlay is only supported on Windows for DirectX or OpenGL games. Linux, Mac, and games using Vulkan are not supported. [Click here for more info.](https://support.discord.com/hc/en-us/articles/217659737-Games-Overlay-101) +::: Discord comes with an awesome built-in overlay, and you may want to make use of it for your game. This manager will help you do just that! It gives you the current state of the overlay for the user, and allows you to update that state. @@ -1376,8 +1384,9 @@ This manager helps retrieve basic user information for any user on Discord. #### GetCurrentUser -> info -> Before calling this function, you'll need to wait for the [OnCurrentUserUpdate](/docs/developer-tools/game-sdk#oncurrentuserupdate) callback to fire after instantiating the User manager. +:::info +Before calling this function, you'll need to wait for the [OnCurrentUserUpdate](/docs/developer-tools/game-sdk#oncurrentuserupdate) callback to fire after instantiating the User manager. +::: Fetch information about the currently connected user account. If you're interested in getting more detailed information about a user—for example, their email—check out our [GetCurrentUser](/docs/resources/user#get-current-user) API endpoint. You'll want to call this with an authorization header of `Bearer `, where `` is the token retrieved from a standard [OAuth2 Authorization Code Grant](/docs/topics/oauth2#authorization-code-grant) flow. diff --git a/docs/discord-social-sdk/core-concepts.mdx b/docs/discord-social-sdk/core-concepts.mdx index 8caefe77fe..86c2f9e550 100644 --- a/docs/discord-social-sdk/core-concepts.mdx +++ b/docs/discord-social-sdk/core-concepts.mdx @@ -47,15 +47,17 @@ The following features are only fully unlocked when joining the closed beta: While these limited access features are available in the Discord Social SDK, their usage is capped with a rate limit. Please read our [documentation on rate limits](/docs/topics/rate-limits) to learn more. -> preview -> To apply for full access to closed beta features or to reach out to Discord directly to discuss your game, please fill out [this form](https://discord.com/developers/social-sdk-closed-beta-access-request-form). +:::preview + To apply for full access to closed beta features or to reach out to Discord directly to discuss your game, please fill out [this form](https://discord.com/developers/social-sdk-closed-beta-access-request-form). +::: --- ## SDK Platform Compatibility -> info -> You can find instructions on how to download the SDK for each platform in the [Getting Started](/docs/discord-social-sdk/getting-started) guide. +:::info +You can find instructions on how to download the SDK for each platform in the [Getting Started](/docs/discord-social-sdk/getting-started) guide. +::: The Discord Social SDK is available for the following platforms: @@ -212,8 +214,9 @@ Some SDK features are currently available but have limited access. Those feature - `openid` - `sdk.social_layer` -> preview -> For more information about these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features). +:::preview + For more information about these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features). +::: The Social SDK provides two helper methods that you can use when setting up your OAuth2 flow: diff --git a/docs/discord-social-sdk/design-guidelines/game-friends.mdx b/docs/discord-social-sdk/design-guidelines/game-friends.mdx index 3b2b4c4523..8fb232f30f 100644 --- a/docs/discord-social-sdk/design-guidelines/game-friends.mdx +++ b/docs/discord-social-sdk/design-guidelines/game-friends.mdx @@ -6,8 +6,9 @@ sidebar_label: Game Friends # {sidebar_label} -> info -> Any in-game imagery used in is purely fictional for concept purposes. +:::info +Any in-game imagery used in is purely fictional for concept purposes. +::: ## User needs diff --git a/docs/discord-social-sdk/design-guidelines/principles.mdx b/docs/discord-social-sdk/design-guidelines/principles.mdx index 1926e3f73a..336f4d43e9 100644 --- a/docs/discord-social-sdk/design-guidelines/principles.mdx +++ b/docs/discord-social-sdk/design-guidelines/principles.mdx @@ -6,8 +6,9 @@ sidebar_label: Principles # Principles -> info -> Any in-game imagery used in is purely fictional for concept purposes. +:::info +Any in-game imagery used in is purely fictional for concept purposes. +::: ## 1. Add Value for the Player diff --git a/docs/discord-social-sdk/design-guidelines/signing-in.mdx b/docs/discord-social-sdk/design-guidelines/signing-in.mdx index b098200d26..85aa80dc31 100644 --- a/docs/discord-social-sdk/design-guidelines/signing-in.mdx +++ b/docs/discord-social-sdk/design-guidelines/signing-in.mdx @@ -6,8 +6,9 @@ sidebar_label: Signing In # Signing In -> info -> Any in-game imagery used in is purely fictional for concept purposes. +:::info +Any in-game imagery used in is purely fictional for concept purposes. +::: ## Overall flow diff --git a/docs/discord-social-sdk/development-guides/account-linking-on-consoles.mdx b/docs/discord-social-sdk/development-guides/account-linking-on-consoles.mdx index 896d38910d..83f1f6d887 100644 --- a/docs/discord-social-sdk/development-guides/account-linking-on-consoles.mdx +++ b/docs/discord-social-sdk/development-guides/account-linking-on-consoles.mdx @@ -139,8 +139,9 @@ To open an authorization screen after requesting the user code, use [`Client::Op client->OpenAuthorizeDeviceScreen(user_code); ``` -> info -> You can also display the `verification_uri_complete` or `verification_uri` with `user_code` in your game's interface to allow the user to enter the code manually. +:::info +You can also display the `verification_uri_complete` or `verification_uri` with `user_code` in your game's interface to allow the user to enter the code manually. +::: ![Authorization screen from using OpenAuthorizeDeviceScreen and GetTokenFromDevice](images/social-sdk/development-guides/authorize_device.png) diff --git a/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list.mdx b/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list.mdx index 50a84895f0..f5723bd0a8 100644 --- a/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list.mdx +++ b/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list.mdx @@ -44,8 +44,9 @@ Presence is how Discord stores whether a user is currently online or not, as wel - Online Status: Online, Offline, Idle, etc. - Rich Presence: Any activities associated with the current game (or application in Discord parlance). -> info +:::info The SDK will only display activities associated with the current game, meaning you will not be able to see other game activities in Rich Presence, even if you can see them in the Discord client. +::: See our [Design Guidelines: Status & Rich Presence](/docs/discord-social-sdk/design-guidelines/status-rich-presence) for best practices on displaying presence information. @@ -129,8 +130,9 @@ Let's update our `DisplayFriendsList` function to reflect our three sections and - We will sort each category alphabetically. - We will display each category separately. -> info -> This example is for reference only. Please make sure you use efficient data structures and cache data when appropriate to avoid performance issues in your game. +:::info +This example is for reference only. Please make sure you use efficient data structures and cache data when appropriate to avoid performance issues in your game. +::: ```cpp void DisplayFriendsList(discordpp::Client& client) { @@ -237,8 +239,9 @@ client->SetRelationshipDeletedCallback([&client](uint64_t userId, bool isDiscord Now your friends list will automatically update when relationships change, such as when you add a new friend, accept a friend request, or block a user. -> warn -> Note: Our example will rebuild the friends list from scratch every time a relationship changes. For performance reasons, you will want to update only the changed relationships. +:::warn +Note: Our example will rebuild the friends list from scratch every time a relationship changes. For performance reasons, you will want to update only the changed relationships. +::: ## Step 4: Monitor Changes to Users @@ -255,8 +258,9 @@ client->SetUserUpdatedCallback([&client](uint64_t userId) { Now your friends list will automatically update when the presence of a friend changes, such as when they go online, offline or start playing your game. -> warn -> Note: Our example will rebuild the friends list from scratch every time a relationship changes. For performance reasons, you will want to update only the user or relationship that changed. +:::warn +Note: Our example will rebuild the friends list from scratch every time a relationship changes. For performance reasons, you will want to update only the user or relationship that changed. +::: --- diff --git a/docs/discord-social-sdk/development-guides/debugging-logging.mdx b/docs/discord-social-sdk/development-guides/debugging-logging.mdx index ce1ca460b9..924efa750d 100644 --- a/docs/discord-social-sdk/development-guides/debugging-logging.mdx +++ b/docs/discord-social-sdk/development-guides/debugging-logging.mdx @@ -16,8 +16,9 @@ This guide will help you understand how to install debugging symbols and handle Debugging symbols are hosted at https://storage.googleapis.com/discord-public-symbols. If using Visual Studio, you can add this link to the pdb locations under `Tools > Options > Debugging > Symbols`. -> info -> Note: You won't be able to browse files using that link, but that's ok. Individual files are accessible under the domain, and the URL functions properly as a symbol server, so it works in Visual Studio. +:::info +Note: You won't be able to browse files using that link, but that's ok. Individual files are accessible under the domain, and the URL functions properly as a symbol server, so it works in Visual Studio. +::: ## Logging @@ -29,8 +30,9 @@ client->AddLogCallback([](auto message, auto severity) { }, discordpp::LoggingSeverity::Info); ``` -> info -> Audio logs are not included in the logs by default. We will update this guide to include audio logs in the future. +:::info +Audio logs are not included in the logs by default. We will update this guide to include audio logs in the future. +::: --- diff --git a/docs/discord-social-sdk/development-guides/joining-voice-chat.mdx b/docs/discord-social-sdk/development-guides/joining-voice-chat.mdx index e696f4b7ff..8e5feda64d 100644 --- a/docs/discord-social-sdk/development-guides/joining-voice-chat.mdx +++ b/docs/discord-social-sdk/development-guides/joining-voice-chat.mdx @@ -15,8 +15,9 @@ import SupportCallout from '../partials/callouts/support.mdx'; Lobbies support voice chat, allowing players to communicate with each other while playing games. -> info -> We will add a **Joining Voice Chat** development guide after GDC. Stay tuned! There is a voice implementation in the Unity sample project that you can reference in the meantime. +:::info +We will add a **Joining Voice Chat** development guide after GDC. Stay tuned! There is a voice implementation in the Unity sample project that you can reference in the meantime. +::: --- diff --git a/docs/discord-social-sdk/development-guides/linked-channels.mdx b/docs/discord-social-sdk/development-guides/linked-channels.mdx index 1f2aaf6194..01de48ebb4 100644 --- a/docs/discord-social-sdk/development-guides/linked-channels.mdx +++ b/docs/discord-social-sdk/development-guides/linked-channels.mdx @@ -60,8 +60,9 @@ Discord allows all channels the user can access in a server to be linked in game It's not possible for the game to know which users should have access to that channel. Every lobby member can view and reply to all messages sent in the linked channel. -> warn -> If you are going to allow private channels to be linked in-game, you must make sure that users are aware that their private channel will be viewable by everyone in the lobby. +:::warn +If you are going to allow private channels to be linked in-game, you must make sure that users are aware that their private channel will be viewable by everyone in the lobby. +::: To help you identify which channels are public or private, we have added a `isViewableAndWriteableByAllMembers` boolean. You can use that boolean to prevent private channels from being linked or to know when to show a clear warning; it's up to you! diff --git a/docs/discord-social-sdk/development-guides/managing-game-invites.mdx b/docs/discord-social-sdk/development-guides/managing-game-invites.mdx index dc76ce4d06..ce143d5fa1 100644 --- a/docs/discord-social-sdk/development-guides/managing-game-invites.mdx +++ b/docs/discord-social-sdk/development-guides/managing-game-invites.mdx @@ -19,8 +19,9 @@ Before you begin, make sure you have: - Set up the Discord Social SDK with our [Getting Started guide](/docs/discord-social-sdk/getting-started) - Familiarized yourself with [Setting Rich Presence](/docs/discord-social-sdk/development-guides/setting-rich-presence) -> info -> Let's talk about the naming of some Discord primitives first. Rich Presence, aka "Activity", can be thought of as the "current activity of a user" and is represented by the [`Activity`] class in the SDK and [in our gateway events](/docs/events/gateway-events#activity-object). This is not to be confused with [Discord Activities](/docs/activities/overview), which are embedded games that can also set and display rich presence. +:::info +Let's talk about the naming of some Discord primitives first. Rich Presence, aka "Activity", can be thought of as the "current activity of a user" and is represented by the [`Activity`] class in the SDK and [in our gateway events](/docs/events/gateway-events#activity-object). This is not to be confused with [Discord Activities](/docs/activities/overview), which are embedded games that can also set and display rich presence. +::: --- @@ -259,8 +260,9 @@ An example flow might look like this: - Once accepted, the new user receives the join secret, and their client can call CreateOrJoinLobby(joinSecret) to join the lobby - Finally, the original user can notice that the lobby membership has changed, so they publish a new Rich Presence update containing the updated party size information -> info -> These examples use client-side lobby management but can also be adapted for lobbies created on the server side. +:::info +These examples use client-side lobby management but can also be adapted for lobbies created on the server side. +::: ### Game Invite with Lobby Example diff --git a/docs/discord-social-sdk/development-guides/managing-lobbies.mdx b/docs/discord-social-sdk/development-guides/managing-lobbies.mdx index c023425a92..d29ee2a0ab 100644 --- a/docs/discord-social-sdk/development-guides/managing-lobbies.mdx +++ b/docs/discord-social-sdk/development-guides/managing-lobbies.mdx @@ -62,8 +62,9 @@ You can use the Discord HTTP API to create, update, and delete lobbies and manag See the [Lobby](/docs/resources/lobby) API resource for available endpoints and [Using with Discord APIs](/docs/discord-social-sdk/development-guides/using-with-discord-apis) for information on how to authenticate your requests. -> info -> Clients will not be able to use [`Client::CreateOrJoinLobby`] or [`Client::LeaveLobby`] with lobbies created using the API. +:::info +Clients will not be able to use [`Client::CreateOrJoinLobby`] or [`Client::LeaveLobby`] with lobbies created using the API. +::: ### Client-Side Lobby Management @@ -107,8 +108,9 @@ Lobbies are intended to be ephemeral and should be cleaned up when the game/matc This value defaults to 5 minutes, and we expect that for most use cases, that will be ok. But we understand there are use cases such as "world chat" that might want to exist longer. The maximum value for this "idle time" will likely be 7 days, so that would mean that the lobby only gets deleted if no one connects to it for an entire week. This should give a good amount of permanence to lobbies when needed, but there may be rare cases where a lobby does need to be "rebuilt" if everyone is offline for an extended period. -> info -> Lobbies created by the SDK client using the [`Client::CreateOrJoinLobby`] function currently have an additional limitation. The "secret" value used in this call expires after 30 days, so the lobby will still exist, but new users won't be able to join the lobby after that. +:::info +Lobbies created by the SDK client using the [`Client::CreateOrJoinLobby`] function currently have an additional limitation. The "secret" value used in this call expires after 30 days, so the lobby will still exist, but new users won't be able to join the lobby after that. +::: --- diff --git a/docs/discord-social-sdk/development-guides/sending-direct-messages.mdx b/docs/discord-social-sdk/development-guides/sending-direct-messages.mdx index fbef333ca0..3360ecaf8c 100644 --- a/docs/discord-social-sdk/development-guides/sending-direct-messages.mdx +++ b/docs/discord-social-sdk/development-guides/sending-direct-messages.mdx @@ -37,8 +37,9 @@ Let's get started with sending a direct message to another user. ## Sending a Direct Message to a User -> info -> While the SDK allows you to send messages on behalf of a user, you must only do so in response to a user action. You should never automatically send messages. +:::info +While the SDK allows you to send messages on behalf of a user, you must only do so in response to a user action. You should never automatically send messages. +::: Here's how to send a direct message. You'll need the recipient's Discord ID and the message you want to send. diff --git a/docs/discord-social-sdk/development-guides/setting-rich-presence.mdx b/docs/discord-social-sdk/development-guides/setting-rich-presence.mdx index b20a81d854..1633ce8be7 100644 --- a/docs/discord-social-sdk/development-guides/setting-rich-presence.mdx +++ b/docs/discord-social-sdk/development-guides/setting-rich-presence.mdx @@ -28,8 +28,9 @@ Rich Presence allows you to display detailed information about players' actions - Friend lists - Server member lists -> info -> Let's talk about the naming of some Discord primitives first. Rich Presence, aka "Activity", can be thought of as the "current activity of a user" and is represented by the [`Activity`] class in the SDK and [in our gateway events](/docs/events/gateway-events#activity-object). This is not to be confused with [Discord Activities](/docs/activities/overview), which are embedded games that can also set and display rich presence. +:::info +Let's talk about the naming of some Discord primitives first. Rich Presence, aka "Activity", can be thought of as the "current activity of a user" and is represented by the [`Activity`] class in the SDK and [in our gateway events](/docs/events/gateway-events#activity-object). This is not to be confused with [Discord Activities](/docs/activities/overview), which are embedded games that can also set and display rich presence. +::: Each [`Activity`] contains fields that describe the following: @@ -47,8 +48,9 @@ Each [`Activity`] contains fields that describe the following: See below for examples of how to set these fields in your code. -> info -> While we support multiple [`ActivityTypes`], games should use `ActivityTypes::Playing` for `type`. The SDK automatically associates activity with your game, so fields like `name` will always show your game's name. +:::info +While we support multiple [`ActivityTypes`], games should use `ActivityTypes::Playing` for `type`. The SDK automatically associates activity with your game, so fields like `name` will always show your game's name. +::: ### Customizing Rich Presence @@ -70,8 +72,9 @@ This diagram visually shows the field mapping: ![Graphical representation of the legend for rich presence details](images/rp-legend.png) -> info -> For tips on designing Rich Presence, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices). +:::info +For tips on designing Rich Presence, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices). +::: --- @@ -95,8 +98,9 @@ Up to 300 custom assets can be added to your app for later use when setting Rich If you need more than 300 custom assets or want to use images stored somewhere else, you can also [specify an external URL](/docs/events/gateway-events#activity-object-activity-asset-image) as long it still has the proper dimensions and size. -> info -> For tips on choosing assets, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices#have-interesting-expressive-art). +:::info +For tips on choosing assets, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices#have-interesting-expressive-art). +::: When uploading Rich Presence assets, **the asset keys will automatically be changed to lowercase**. You can see this reflected in your app's settings after saving a newly uploaded asset, and you should keep it in mind when referencing any asset keys in your code. @@ -155,8 +159,9 @@ assets.SetSmallText("Tank"); activity.SetAssets(assets); ``` -> info -> If you need more than 300 custom assets or want to use images stored somewhere else, you can also [specify an external URL](/docs/events/gateway-events#activity-object-activity-asset-image) as long it still has the proper dimensions and size. +:::info +If you need more than 300 custom assets or want to use images stored somewhere else, you can also [specify an external URL](/docs/events/gateway-events#activity-object-activity-asset-image) as long it still has the proper dimensions and size. +::: --- diff --git a/docs/discord-social-sdk/development-guides/using-provisional-accounts.mdx b/docs/discord-social-sdk/development-guides/using-provisional-accounts.mdx index 01702b9f8f..29dafb1f33 100644 --- a/docs/discord-social-sdk/development-guides/using-provisional-accounts.mdx +++ b/docs/discord-social-sdk/development-guides/using-provisional-accounts.mdx @@ -121,8 +121,9 @@ The callback function will be invoked with an access token that expires in 1 hou You can use [`Client::SetTokenExpirationCallback`] to receive a callback when the current token is about to expire or expires. -> info -> When the token expires, the SDK will still receive updates, such as new messages sent in a lobby, and any voice calls will continue to be active. However, any new actions, such as sending a message or adding a friend, will fail. You can get a new token and pass it to UpdateToken without interrupting the user's experience. +:::info +When the token expires, the SDK will still receive updates, such as new messages sent in a lobby, and any voice calls will continue to be active. However, any new actions, such as sending a message or adding a friend, will fail. You can get a new token and pass it to UpdateToken without interrupting the user's experience. +::: #### Provisional Account Access Token Storage diff --git a/docs/discord-social-sdk/development-guides/using-with-discord-apis.mdx b/docs/discord-social-sdk/development-guides/using-with-discord-apis.mdx index 45550d8e32..fd4b699be9 100644 --- a/docs/discord-social-sdk/development-guides/using-with-discord-apis.mdx +++ b/docs/discord-social-sdk/development-guides/using-with-discord-apis.mdx @@ -31,8 +31,9 @@ curl -X GET https://discord.com/api/v10/users/@me \ -H "Authorization: Bot YOUR_BOT_TOKEN" ``` -> info -> Always prefix your bot token with `Bot ` in the Authorization header! +:::info +Always prefix your bot token with `Bot ` in the Authorization header! +::: ### Bearer Token Authentication For authenticated user actions: diff --git a/docs/discord-social-sdk/getting-started.mdx b/docs/discord-social-sdk/getting-started.mdx index 7ae616eb22..386d808169 100644 --- a/docs/discord-social-sdk/getting-started.mdx +++ b/docs/discord-social-sdk/getting-started.mdx @@ -32,8 +32,9 @@ If you are unsure which platform to choose, we recommend starting with the C++ g -> info -> To see a complete list of currently compatible platforms, check out our [Platform Compatibility](/docs/discord-social-sdk/core-concepts#sdk-platform-compatibility) section. +:::info +To see a complete list of currently compatible platforms, check out our [Platform Compatibility](/docs/discord-social-sdk/core-concepts#sdk-platform-compatibility) section. +::: --- diff --git a/docs/discord-social-sdk/getting-started/partials/getting-started.mdx b/docs/discord-social-sdk/getting-started/partials/getting-started.mdx index 2afded95c0..6f2dc6925a 100644 --- a/docs/discord-social-sdk/getting-started/partials/getting-started.mdx +++ b/docs/discord-social-sdk/getting-started/partials/getting-started.mdx @@ -18,8 +18,9 @@ Later, you can invite your team members to your new team to collaborate on your - See [`discordpp::Client::Authorize`](https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ace94a58e27545a933d79db32b387a468) for more details on setting up more advanced redirect URIs. 4. Enable the `Public Client` toggle in the `OAuth2` tab. -> warn -> **Note:** This guide requires enabling **Public Client** to allow you to get started with the SDK quickly. Most games will not want to ship as a public client. This setting should be reviewed by your team prior to releasing your game. [Learn more about public clients](/docs/discord-social-sdk/core-concepts#oauth2-client-types). +:::warn +**Note:** This guide requires enabling **Public Client** to allow you to get started with the SDK quickly. Most games will not want to ship as a public client. This setting should be reviewed by your team prior to releasing your game. [Learn more about public clients](/docs/discord-social-sdk/core-concepts#oauth2-client-types). +::: --- diff --git a/docs/discord-social-sdk/getting-started/using-c++.mdx b/docs/discord-social-sdk/getting-started/using-c++.mdx index 7ebc9b7db9..9cdcd8c843 100644 --- a/docs/discord-social-sdk/getting-started/using-c++.mdx +++ b/docs/discord-social-sdk/getting-started/using-c++.mdx @@ -61,8 +61,9 @@ To utilize the Discord Social SDK with C++, the following requirements must be m All of which can be found in the SDK download archive. -> info -> 💡 **Troubleshooting Tip:** If you encounter unresolved external symbols, ensure the SDK library is correctly linked in your build system. +:::info +💡 **Troubleshooting Tip:** If you encounter unresolved external symbols, ensure the SDK library is correctly linked in your build system. +::: Let's see this in action by starting with a folder for our project and the Social SDK dependency: @@ -285,18 +286,19 @@ int main() { ``` -> info -> Most Discord features won't work until the status is [`Client::Status::Ready`]. The status callback lets you know -> exactly when you can start using them. +:::info +Most Discord features won't work until the status is [`Client::Status::Ready`]. The status callback lets you know exactly when you can start using them. +::: ### What These Callbacks Do - The **logging callback** shows you what's happening behind the scenes - The **status callback** tells you when you're connected and ready to use Discord features -> info -> At this point, these callbacks **won't get called** since the client setup is not yet complete. However, very soon we -> will be using them to view debug information and see what our connection status is! +:::info +At this point, these callbacks **won't get called** since the client setup is not yet complete. However, very soon we +will be using them to view debug information and see what our connection status is! +::: To get to a [`Client::Status::Ready`] state, we need to authenticate with Discord. We'll do that shortly. @@ -370,8 +372,9 @@ client->Authorize(args, [client, codeVerifier](auto result, auto code, auto redi 3. Start the auth flow with [`Client::Authorize`], which opens a browser 4. When authorized, we exchange the code for an access token -> warn -> Never log or store access tokens insecurely! They should be treated as sensitive credentials. +:::warn +Never log or store access tokens insecurely! They should be treated as sensitive credentials. +::: ### Testing It Out @@ -498,8 +501,9 @@ client->UpdateToken(discordpp::AuthorizationTokenType::Bearer, accessToken, [cl 3. The SDK will begin connecting asynchronously 4. Our status callback (from Step 6) will tell us when we're ready -> info -> Watch your console output! You should see status updates as the connection is established. +:::info +Watch your console output! You should see status updates as the connection is established. +::: ### Testing the Connection @@ -640,8 +644,9 @@ std::cout << "👥 Friends Count: " << client->GetRelationships().size() << std: 1. Run your program 2. Wait for the initial friend count -> info -> This relationship data forms the foundation for features like friend lists, activity feeds, and multiplayer invites! +:::info +This relationship data forms the foundation for features like friend lists, activity feeds, and multiplayer invites! +::: ### Troubleshooting diff --git a/docs/discord-social-sdk/getting-started/using-unity.mdx b/docs/discord-social-sdk/getting-started/using-unity.mdx index 6569129c85..d377ae1133 100644 --- a/docs/discord-social-sdk/getting-started/using-unity.mdx +++ b/docs/discord-social-sdk/getting-started/using-unity.mdx @@ -39,8 +39,9 @@ Let's walk through the steps in detail. 1. Click on the `Downloads` link under the Discord Social SDK section of the sidebar. 2. Select the latest version from the version dropdown and download the SDK for Unity. -> info -> A Unity sample project is available for download on this page, but we are not going to cover it in this guide. Explore it on your own after you finish this guide! +:::info +A Unity sample project is available for download on this page, but we are not going to cover it in this guide. Explore it on your own after you finish this guide! +::: --- @@ -153,11 +154,13 @@ This will hook up the API status changes to your text in the game. Then we'll ne - The **logging callback** shows you what's happening behind the scenes and is a powerful tool for debugging - The **status callback** tells you when you're connected and ready to use Discord features -> info -> The Unity plugin handles running the SDK callbacks for you in Unity, no need to use [`RunCallbacks`] like we do in the [C++ guide](/docs/discord-social-sdk/getting-started/using-c++). +:::info +The Unity plugin handles running the SDK callbacks for you in Unity, no need to use [`RunCallbacks`] like we do in the [C++ guide](/docs/discord-social-sdk/getting-started/using-c++). +::: -> info -> Most Discord features won't work until the status is `Ready`. The status callback lets you know when you can start using them. +:::info +Most Discord features won't work until the status is `Ready`. The status callback lets you know when you can start using them. +::: To get to a `Ready` state, we need to authenticate with Discord. Let's do that next. @@ -219,8 +222,9 @@ and then we'll uncomment `loginButton.onClick.AddListener(StartOAuthFlow);` in y 3. Start the auth flow with [`Client::Authorize`], which opens a browser 4. When authorized, we exchange the code for an access token -> warn -> Never log or store access tokens insecurely! They should be treated as sensitive credentials. +:::warn +Never log or store access tokens insecurely! They should be treated as sensitive credentials. +::: ### Testing It Out diff --git a/docs/discord-social-sdk/getting-started/using-unreal-engine.mdx b/docs/discord-social-sdk/getting-started/using-unreal-engine.mdx index edaf70901e..0a0dd66615 100644 --- a/docs/discord-social-sdk/getting-started/using-unreal-engine.mdx +++ b/docs/discord-social-sdk/getting-started/using-unreal-engine.mdx @@ -19,8 +19,9 @@ This guide will walk you through integrating the Discord Social SDK into an Unre - Start the SDK and establish a connection - Request the number of Discord friends the player has -> info -> For the initial launch, the Unreal plugin has a name of `DiscordPartnerSDK` but this name will be changing to `DiscordSocialSDK` in a future version +:::info +For the initial launch, the Unreal plugin has a name of `DiscordPartnerSDK` but this name will be changing to `DiscordSocialSDK` in a future version +::: ### Prerequisites @@ -43,8 +44,9 @@ Let's walk through the steps in detail. 1. Click on the `Downloads` link under the Discord Social SDK section of the sidebar. 2. Select the latest version from the version dropdown and download the SDK for Unreal Engine. -> info -> A Unreal Engine sample project is available for download on this page, but we are not going to cover it in this guide. Explore it on your own after you finish this guide! +:::info +A Unreal Engine sample project is available for download on this page, but we are not going to cover it in this guide. Explore it on your own after you finish this guide! +::: --- @@ -54,8 +56,9 @@ Let's walk through the steps in detail. Select Third Person Unreal project (C++ language). We'll set the project name to `DiscordSocialUnreal`. -> info -> The code samples below assume the project name is `DiscordSocialUnreal`. If you use a different name, make sure to replace it in the code. +:::info +The code samples below assume the project name is `DiscordSocialUnreal`. If you use a different name, make sure to replace it in the code. +::: Wait for the shaders to compile. This can take a while. @@ -67,8 +70,9 @@ Create a new directory named `Plugins` in the base of your project directory (`D Extract the Discord SDK archive in the Plugins directory. You should end up with a directory called `DiscordPartnerSDK` inside of Plugins `DiscordSocialUnreal/Plugins/DiscordPartnerSDK`. -> info -> Double check the name of the `DiscordPartnerSDK` folder once you've extracted it. It may change between versions and you'll need to add the correct name in the code below. +:::info +Double check the name of the `DiscordPartnerSDK` folder once you've extracted it. It may change between versions and you'll need to add the correct name in the code below. +::: Reload Unreal Editor and open the project. It should ask if you'd like to recompile the `DiscordPartnerSDK` plugin on launch. @@ -228,8 +232,9 @@ If Discord is open on your computer, you should see a prompt to authorize the co If the connection is successful, you should see a message in the Unreal Editor console that says, "Connected to Discord! Ready to go! You can now start using Discord features." -> info -> Most Discord features won't work until the status is `Ready`. The status callback lets you know when you can start using them. +:::info +Most Discord features won't work until the status is `Ready`. The status callback lets you know when you can start using them. +::: ### Troubleshooting diff --git a/docs/discord-social-sdk/overview.mdx b/docs/discord-social-sdk/overview.mdx index 0454136f9d..1abaff40b4 100644 --- a/docs/discord-social-sdk/overview.mdx +++ b/docs/discord-social-sdk/overview.mdx @@ -42,8 +42,9 @@ Start integrating the SDK into your game with our getting started guides, design Discord Social SDK features for text and voice communication are available but have limited access. -> preview -> For more information on how to access these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features). +:::preview + For more information on how to access these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features). +::: --- diff --git a/docs/discord-social-sdk/partials/callouts/console-access.mdx b/docs/discord-social-sdk/partials/callouts/console-access.mdx index 3e197731b1..7ab12301b2 100644 --- a/docs/discord-social-sdk/partials/callouts/console-access.mdx +++ b/docs/discord-social-sdk/partials/callouts/console-access.mdx @@ -1,2 +1,3 @@ -> info -> To use the Discord Social SDK in your console games, you will need to request middleware approval and be an approved developer for the target console. Check out [this article](https://support-dev.discord.com/hc/en-us/articles/30209074764183) to learn more. +:::info +To use the Discord Social SDK in your console games, you will need to request middleware approval and be an approved developer for the target console. Check out [this article](https://support-dev.discord.com/hc/en-us/articles/30209074764183) to learn more. +::: diff --git a/docs/discord-social-sdk/partials/callouts/limited-access.mdx b/docs/discord-social-sdk/partials/callouts/limited-access.mdx index c95b5103aa..49edead8e4 100644 --- a/docs/discord-social-sdk/partials/callouts/limited-access.mdx +++ b/docs/discord-social-sdk/partials/callouts/limited-access.mdx @@ -1,2 +1,3 @@ -> preview -> This feature is currently available with [limited access](/docs/discord-social-sdk/core-concepts#limited-access-features). To apply for full access to closed beta features, or to reach out to Discord directly to discuss your game, please fill out [this form](https://discord.com/developers/social-sdk-closed-beta-access-request-form). \ No newline at end of file +:::preview + This feature is currently available with [limited access](/docs/discord-social-sdk/core-concepts#limited-access-features). To apply for full access to closed beta features, or to reach out to Discord directly to discuss your game, please fill out [this form](https://discord.com/developers/social-sdk-closed-beta-access-request-form). +::: \ No newline at end of file diff --git a/docs/discord-social-sdk/partials/callouts/public-client.mdx b/docs/discord-social-sdk/partials/callouts/public-client.mdx index 3a9ae63151..3c6adebda4 100644 --- a/docs/discord-social-sdk/partials/callouts/public-client.mdx +++ b/docs/discord-social-sdk/partials/callouts/public-client.mdx @@ -1,2 +1,3 @@ -> warn -> This method requires enabling **Public Client** for your app. Most games will not want to ship with this enabled. [Learn more](/docs/discord-social-sdk/core-concepts#oauth2-client-types) \ No newline at end of file +:::warn +This method requires enabling **Public Client** for your app. Most games will not want to ship with this enabled. [Learn more](/docs/discord-social-sdk/core-concepts#oauth2-client-types) +::: \ No newline at end of file diff --git a/docs/discovery/best-practices.md b/docs/discovery/best-practices.md index 16c5821a86..32b8513d42 100644 --- a/docs/discovery/best-practices.md +++ b/docs/discovery/best-practices.md @@ -6,8 +6,9 @@ sidebar_label: Best Practices So you’ve made an app on Discord and are ready to opt in to discovery on the App Directory! Or maybe you have already listed your app but aren’t seeing as much traction to it as you’d like? Whatever stage you’re at, this guide has some tips and tricks from your friendly Discord Staff members to help boost performance of your App Directory Product Page. -> info -> This guide references settings and information you can set up and modify within your [app's settings](https://discord.com/developers/applications). If you don't have an app yet, you can follow the [Getting Started guide](/docs/quick-start/getting-started). +:::info +This guide references settings and information you can set up and modify within your [app's settings](https://discord.com/developers/applications). If you don't have an app yet, you can follow the [Getting Started guide](/docs/quick-start/getting-started). +::: ## The Elevator Pitch @@ -15,8 +16,9 @@ So you’ve made an app on Discord and are ready to opt in to discovery on the A App descriptions should convey the value of your app and what it does. Make your app descriptions punchy and to the point - letting folks know what your app does in simple terms while also exciting the potential user to add the app and start using it. -> info -> Be sure to spell check and review your grammar before posting your descriptions. Your app has the potential to be seen by millions of people! +:::info +Be sure to spell check and review your grammar before posting your descriptions. Your app has the potential to be seen by millions of people! +::: There are a few places where you can define different descriptions of your app within your [app's settings](https://discord.com/developers/applications). @@ -76,8 +78,9 @@ Think of up to five words that describe your app and add them as tags (see image Your app’s support server is a paramount part of your App Product Page. It’s important to ensure your app has a dedicated server and channel for communication between your app’s users and its developers and maintainers. -> info -> If your support server isn't [discoverable](https://support.discord.com/hc/en-us/articles/360030843331-Enabling-Server-Discovery), be sure to include an invite link in the "links" section of your App Directory Product Page. +:::info +If your support server isn't [discoverable](https://support.discord.com/hc/en-us/articles/360030843331-Enabling-Server-Discovery), be sure to include an invite link in the "links" section of your App Directory Product Page. +::: Some ways you can successfully use your support server includes: diff --git a/docs/discovery/enabling-discovery.mdx b/docs/discovery/enabling-discovery.mdx index cde564641e..9681525a67 100644 --- a/docs/discovery/enabling-discovery.mdx +++ b/docs/discovery/enabling-discovery.mdx @@ -34,8 +34,9 @@ To opt into **Discovery**: For more information on **Discovery**, check out our [Help Center article](https://support-dev.discord.com/hc/en-us/articles/21204493235991-How-Can-Users-Discover-and-Play-My-Activity). -> info -> Once you enable **Discovery**, it may take up to 24 hours for your app to appear in the App Directory and App Launcher. +:::info +Once you enable **Discovery**, it may take up to 24 hours for your app to appear in the App Directory and App Launcher. +::: ### Search for your App in Discord To check if your app is discoverable, search for it in the App Directory or App Launcher. diff --git a/docs/events/gateway-events.mdx b/docs/events/gateway-events.mdx index 1052eeb55a..c0754b47d3 100644 --- a/docs/events/gateway-events.mdx +++ b/docs/events/gateway-events.mdx @@ -13,8 +13,9 @@ All Gateway events are encapsulated in a [Gateway event payload](/docs/events/ga For more information about interacting with the Gateway, you can reference the [Gateway documentation](/docs/events/gateway). -> warn -> Not all Gateway event fields are documented. You should assume that undocumented fields are not supported for apps, and their format and data may change at any time. +:::warn +Not all Gateway event fields are documented. You should assume that undocumented fields are not supported for apps, and their format and data may change at any time. +::: ### Event Names @@ -50,8 +51,9 @@ Gateway event payloads have a common structure, but the contents of the associat Send events are Gateway events encapsulated in an [event payload](/docs/events/gateway-events#payload-structure), and are sent by an app to Discord through a Gateway connection. -> info -> Previously, Gateway send events were labeled as commands +:::info +Previously, Gateway send events were labeled as commands +::: | Name | Description | |------------------------------------------------------------------------------------|-----------------------------------------------------------| @@ -89,8 +91,9 @@ Details about identifying is in the [Gateway documentation](/docs/events/gateway | browser | string | Your library name | | device | string | Your library name | -> warn -> These fields originally were $ prefixed (i.e: `$browser`) but [this syntax is deprecated](/docs/change-log#updated-connection-property-field-names). While they currently still work, it is recommended to move to non-prefixed fields. +:::warn +These fields originally were $ prefixed (i.e: `$browser`) but [this syntax is deprecated](/docs/change-log#updated-connection-property-field-names). While they currently still work, it is recommended to move to non-prefixed fields. +::: ###### Example Identify @@ -188,8 +191,9 @@ Due to our privacy and infrastructural concerns with this feature, there are som | user_ids? | snowflake or array of snowflakes | used to specify which users you wish to fetch | one of query or user_ids | | nonce? | string | nonce to identify the [Guild Members Chunk](/docs/events/gateway-events#guild-members-chunk) response | false | -> info -> Nonce can only be up to 32 bytes. If you send an invalid nonce it will be ignored and the reply member_chunk(s) will not have a nonce set. +:::info +Nonce can only be up to 32 bytes. If you send an invalid nonce it will be ignored and the reply member_chunk(s) will not have a nonce set. +::: ###### Example Request Guild Members @@ -587,15 +591,17 @@ Sent when a message is pinned or unpinned in a text channel. This is not sent wh #### Entitlement Create -> warn -> Note: The`ENTITLEMENT_CREATE` event behavior changed on October 1, 2024. Please see the [Change Log and Entitlement Migration Guide](/docs/change-log#premium-apps-entitlement-migration-and-new-subscription-api) for more information on what changed. +:::warn +Note: The`ENTITLEMENT_CREATE` event behavior changed on October 1, 2024. Please see the [Change Log and Entitlement Migration Guide](/docs/change-log#premium-apps-entitlement-migration-and-new-subscription-api) for more information on what changed. +::: Sent when an entitlement is created. The inner payload is an [entitlement](/docs/resources/entitlement#entitlement-object) object. #### Entitlement Update -> warn -> Note: The`ENTITLEMENT_UPDATE` event behavior changed on October 1, 2024. Please see the [Change Log and Entitlement Migration Guide](/docs/change-log#premium-apps-entitlement-migration-and-new-subscription-api) for more information on what changed. +:::warn +Note: The`ENTITLEMENT_UPDATE` event behavior changed on October 1, 2024. Please see the [Change Log and Entitlement Migration Guide](/docs/change-log#premium-apps-entitlement-migration-and-new-subscription-api) for more information on what changed. +::: Sent when an entitlement is updated. The inner payload is an [entitlement](/docs/resources/entitlement#entitlement-object) object. @@ -623,8 +629,9 @@ This event can be sent in three different scenarios: 2. When a Guild becomes available again to the client. 3. When the current user joins a new Guild. -> note -> During an outage, the guild object in scenarios 1 and 3 may be marked as unavailable. +:::info +During an outage, the guild object in scenarios 1 and 3 may be marked as unavailable. +::: The inner payload can be: @@ -648,8 +655,9 @@ The inner payload can be: | guild_scheduled_events | array of [guild scheduled event](/docs/resources/guild-scheduled-event#guild-scheduled-event-object) objects | Scheduled events in the guild | | soundboard_sounds | array of [soundboard sound](/docs/resources/soundboard#soundboard-sound-object) objects | Soundboard sounds in the guild | -> warn -> If your bot does not have the `GUILD_PRESENCES` [Gateway Intent](/docs/events/gateway#gateway-intents), or if the guild has over 75k members, members and presences returned in this event will only contain your bot and users in voice channels. +:::warn +If your bot does not have the `GUILD_PRESENCES` [Gateway Intent](/docs/events/gateway#gateway-intents), or if the guild has over 75k members, members and presences returned in this event will only contain your bot and users in voice channels. +::: #### Guild Update @@ -725,8 +733,9 @@ Sent when a guild integration is updated. #### Guild Member Add -> warn -> If using [Gateway Intents](/docs/events/gateway#gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. +:::warn +If using [Gateway Intents](/docs/events/gateway#gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. +::: Sent when a new user joins a guild. The inner payload is a [guild member](/docs/resources/guild#guild-member-object) object with an extra `guild_id` key: @@ -738,8 +747,9 @@ Sent when a new user joins a guild. The inner payload is a [guild member](/docs/ #### Guild Member Remove -> warn -> If using [Gateway Intents](/docs/events/gateway#gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. +:::warn +If using [Gateway Intents](/docs/events/gateway#gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. +::: Sent when a user is removed from a guild (leave/kick/ban). @@ -752,8 +762,9 @@ Sent when a user is removed from a guild (leave/kick/ban). #### Guild Member Update -> warn -> If using [Gateway Intents](/docs/events/gateway#gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. +:::warn +If using [Gateway Intents](/docs/events/gateway#gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. +::: Sent when a guild member is updated. This will also fire when the user object of a guild member changes. @@ -976,8 +987,9 @@ Sent when an invite is deleted. ### Messages -> warn -> Unlike persistent messages, ephemeral messages are sent directly to the user and the bot who sent the message rather than through the guild channel. Because of this, ephemeral messages are tied to the [`DIRECT_MESSAGES` intent](/docs/events/gateway#list-of-intents), and the message object won't include `guild_id` or `member`. +:::warn +Unlike persistent messages, ephemeral messages are sent directly to the user and the bot who sent the message rather than through the guild channel. Because of this, ephemeral messages are tied to the [`DIRECT_MESSAGES` intent](/docs/events/gateway#list-of-intents), and the message object won't include `guild_id` or `member`. +::: #### Message Create @@ -995,8 +1007,9 @@ Sent when a message is created. The inner payload is a [message](/docs/resources Sent when a message is updated. The inner payload is a [message](/docs/resources/message#message-object) object with the same extra fields as [MESSAGE_CREATE](/docs/events/gateway-events#message-create). -> warn -> The value for `tts` will always be false in message updates. +:::warn +The value for `tts` will always be false in message updates. +::: #### Message Delete @@ -1086,13 +1099,15 @@ Sent when a bot removes all instances of a given emoji from the reactions of a m #### Presence Update -> warn -> If you are using [Gateway Intents](/docs/events/gateway#gateway-intents), you _must_ specify the `GUILD_PRESENCES` intent in order to receive Presence Update events +:::warn +If you are using [Gateway Intents](/docs/events/gateway#gateway-intents), you _must_ specify the `GUILD_PRESENCES` intent in order to receive Presence Update events +::: A user's presence is their current state on a guild. This event is sent when a user's presence or info, such as name or avatar, is updated. -> warn -> The user object within this event can be partial, the only field which must be sent is the `id` field, everything else is optional. Along with this limitation, no fields are required, and the types of the fields are **not** validated. Your client should expect any combination of fields and types within this event. +:::warn +The user object within this event can be partial, the only field which must be sent is the `id` field, everything else is optional. Along with this limitation, no fields are required, and the types of the fields are **not** validated. Your client should expect any combination of fields and types within this event. +::: ###### Presence Update Event Fields @@ -1136,8 +1151,9 @@ Active sessions are indicated with an "online", "idle", or "dnd" string per plat | flags? | integer | [Activity flags](/docs/events/gateway-events#activity-object-activity-flags) `OR`d together, describes what the payload includes | | buttons? | array of [buttons](/docs/events/gateway-events#activity-object-activity-buttons) | Custom buttons shown in the Rich Presence (max 2) | -> info -> Bot users are only able to set `name`, `state`, `type`, and `url`. +:::info +Bot users are only able to set `name`, `state`, `type`, and `url`. +::: ###### Activity Types @@ -1150,8 +1166,9 @@ Active sessions are indicated with an "online", "idle", or "dnd" string per plat | 4 | Custom | `{emoji}` `{state}` | ":smiley: I am cool" | | 5 | Competing | Competing in `{name}` | "Competing in Arena World Champions" | -> info -> The streaming type currently only supports Twitch and YouTube. Only `https://twitch.tv/` and `https://youtube.com/` urls will work. +:::info +The streaming type currently only supports Twitch and YouTube. Only `https://twitch.tv/` and `https://youtube.com/` urls will work. +::: ###### Activity Timestamps @@ -1160,8 +1177,9 @@ Active sessions are indicated with an "online", "idle", or "dnd" string per plat | start? | integer | Unix time (in milliseconds) of when the activity started | | end? | integer | Unix time (in milliseconds) of when the activity ends | -> info -> For Listening and Watching activities, you can include both start and end timestamps to display a time bar. +:::info +For Listening and Watching activities, you can include both start and end timestamps to display a time bar. +::: ###### Activity Emoji @@ -1271,8 +1289,9 @@ When received over the gateway, the `buttons` field is an array of strings, whic } ``` -> warn -> Clients may only update their game status 5 times per 20 seconds. +:::warn +Clients may only update their game status 5 times per 20 seconds. +::: #### Typing Start @@ -1326,8 +1345,9 @@ Sent when someone joins/leaves/moves voice channels. Inner payload is a [voice s Sent when a guild's voice server is updated. This is sent when initially connecting to voice, and when the current voice instance fails over to a new server. -> warn -> A null endpoint means that the voice server allocated has gone away and is trying to be reallocated. You should attempt to disconnect from the currently connected voice server, and not attempt to reconnect until a new voice server is allocated. +:::warn +A null endpoint means that the voice server allocated has gone away and is trying to be reallocated. You should attempt to disconnect from the currently connected voice server, and not attempt to reconnect until a new voice server is allocated. +::: ###### Voice Server Update Event Fields @@ -1384,8 +1404,9 @@ Sent when a [Stage instance](/docs/resources/stage-instance) has been deleted (i #### Subscription Create -> info -> Subscription status should not be used to grant perks. Use [entitlements](/docs/resources/entitlement#entitlement-object) as an indication of whether a user should have access to a specific SKU. See our guide on [Implementing App Subscriptions](/docs/monetization/implementing-app-subscriptions) for more information. +:::info +Subscription status should not be used to grant perks. Use [entitlements](/docs/resources/entitlement#entitlement-object) as an indication of whether a user should have access to a specific SKU. See our guide on [Implementing App Subscriptions](/docs/monetization/implementing-app-subscriptions) for more information. +::: Sent when a [Subscription](/docs/resources/subscription) for a Premium App is created. Inner payload is a [Subscription](/docs/resources/subscription#subscription-object). diff --git a/docs/events/gateway.mdx b/docs/events/gateway.mdx index abe9c4794d..f2753acccc 100644 --- a/docs/events/gateway.mdx +++ b/docs/events/gateway.mdx @@ -6,8 +6,9 @@ sidebar_label: Using Gateway The Gateway API lets apps open secure WebSocket connections with Discord to receive events about actions that take place in a server/guild, like when a channel is updated or a role is created. There are a few cases where apps will *also* use Gateway connections to update or request resources, like when updating voice state. -> info -> In *most* cases, performing REST operations on Discord resources can be done using the [HTTP API](/docs/reference#http-api) rather than the Gateway API. +:::info +In *most* cases, performing REST operations on Discord resources can be done using the [HTTP API](/docs/reference#http-api) rather than the Gateway API. +::: The Gateway is Discord's form of real-time communication used by clients (including apps), so there are nuances and data passed that simply isn't relevant to apps. Interacting with the Gateway can be tricky, but there are [community-built libraries](/docs/developer-tools/community-resources#libraries) with built-in support that simplify the most complicated bits and pieces. If you're planning on writing a custom implementation, be sure to read the following documentation in its entirety so you understand the sacred secrets of the Gateway (or at least those that matter for apps). @@ -36,8 +37,9 @@ Details about Gateway event payloads are in the [Gateway events documentation](/ When sending a Gateway event (like when [performing an initial handshake](/docs/events/gateway-events#identify) or [updating presence](/docs/events/gateway-events#update-presence)), your app must send an [event payload object](/docs/events/gateway-events#payload-structure) with a valid opcode (`op`) and inner data object (`d`). -> info -> Specific rate limits are applied when sending events, which you can read about in the [Rate Limiting](/docs/events/gateway#rate-limiting) section. +:::info +Specific rate limits are applied when sending events, which you can read about in the [Rate Limiting](/docs/events/gateway#rate-limiting) section. +::: Event payloads sent over a Gateway connection: @@ -71,8 +73,9 @@ Gateway connections are persistent WebSockets which introduce more complexity th ### Connection Lifecycle -> info -> There are nuances that aren't included in the overview below. More details about each step and event can be found in the individual sections below. +:::info +There are nuances that aren't included in the overview below. More details about each step and event can be found in the individual sections below. +::: At a high-level, Gateway connections consist of the following cycle: @@ -96,11 +99,13 @@ When initially calling either [Get Gateway](/docs/events/gateway#get-gateway) or When connecting to the URL, it's a good idea to explicitly pass the API version and [encoding](/docs/events/gateway#encoding-and-compression) as query parameters. You can also optionally include whether Discord should [compress](/docs/events/gateway#encoding-and-compression) data that it sends your app. -> info -> `wss://gateway.discord.gg/?v=10&encoding=json` is an example of a WSS URL an app may use to connect to the Gateway. +:::info +`wss://gateway.discord.gg/?v=10&encoding=json` is an example of a WSS URL an app may use to connect to the Gateway. +::: -> warn -> For security reasons, the Gateway cannot be accessed directly from a Cloudflare Worker. Attempts will result in a 401 Unauthorized status code. +:::warn +For security reasons, the Gateway cannot be accessed directly from a Cloudflare Worker. Attempts will result in a 401 Unauthorized status code. +::: ###### Gateway URL Query String Params @@ -139,8 +144,9 @@ Upon receiving the Hello event, your app should wait `heartbeat_interval * jitte When sending a heartbeat, your app will need to include the last sequence number your app received in the `d` field. The sequence number is sent to your app in the [event payload](/docs/events/gateway-events#payload-structure) in the `s` field. If your app hasn't received any events yet, you can just pass `null` in the `d` field. -> info -> In the first heartbeat, `jitter` is an offset value between 0 and `heartbeat_interval` that is meant to prevent too many clients (both desktop and apps) from reconnecting their sessions at the exact same time (which could cause an influx of traffic). +:::info +In the first heartbeat, `jitter` is an offset value between 0 and `heartbeat_interval` that is meant to prevent too many clients (both desktop and apps) from reconnecting their sessions at the exact same time (which could cause an influx of traffic). +::: You *can* send heartbeats before the `heartbeat_interval` elapses, but you should avoid doing so unless necessary. There is already tolerance in the `heartbeat_interval` that will cover network latency, so you don't need to account for it in your implementation. @@ -154,8 +160,9 @@ When you send a Heartbeat event, Discord will respond with a [Heartbeat ACK (opc } ``` -> info -> In the event of a service outage where you stay connected to the Gateway, you should continue to send heartbeats and receive heartbeat ACKs. The Gateway will eventually respond and issue a session once it's able to. +:::info +In the event of a service outage where you stay connected to the Gateway, you should continue to send heartbeats and receive heartbeat ACKs. The Gateway will eventually respond and issue a session once it's able to. +::: If a client does not receive a heartbeat ACK between its attempts at sending heartbeats, this may be due to a failed or "zombied" connection. The client should immediately terminate the connection with any close code besides `1000` or `1001`, then reconnect and attempt to [Resume](/docs/events/gateway#resuming). @@ -173,8 +180,9 @@ Apps are limited by maximum concurrency (`max_concurrency` in the [session start After your app sends a valid Identify payload, Discord will respond with a [Ready](/docs/events/gateway-events#ready) event which indicates that your app is in a successfully-connected state with the Gateway. The Ready event is sent as a standard [Dispatch (opcode `0`)](/docs/topics/opcodes-and-status-codes#gateway-gateway-opcodes). -> warn -> Clients are limited to 1000 `IDENTIFY` calls to the websocket in a 24-hour period. This limit is global and across all shards, but does not include `RESUME` calls. Upon hitting this limit, all active sessions for the app will be terminated, the bot token will be reset, and the owner will receive an email notification. It's up to the owner to update their application with the new token. +:::warn +Clients are limited to 1000 `IDENTIFY` calls to the websocket in a 24-hour period. This limit is global and across all shards, but does not include `RESUME` calls. Upon hitting this limit, all active sessions for the app will be terminated, the bot token will be reset, and the owner will receive an email notification. It's up to the owner to update their application with the new token. +::: ###### Example Identify Payload @@ -251,8 +259,9 @@ When Resuming, you do not need to send an Identify event after opening the conne If successful, the Gateway will send the missed events in order, finishing with a [Resumed](/docs/events/gateway-events#resumed) event to signal event replay has finished and that all subsequent events will be new. -> info -> When resuming with the `resume_gateway_url` you need to provide the same version and encoding as the initial connection. +:::info +When resuming with the `resume_gateway_url` you need to provide the same version and encoding as the initial connection. +::: It's possible your app won't reconnect in time to Resume, in which case it will receive an [Invalid Session (opcode `9`)](/docs/events/gateway-events#invalid-session) event. If the `d` field is set to `false` (which is most of the time), your app should disconnect. After disconnect, your app should create a new connection with your cached URL from the [Get Gateway](/docs/events/gateway#get-gateway) or the [Get Gateway Bot](/docs/events/gateway#get-gateway-bot) endpoint, then send an [Identify (opcode `2`)](/docs/events/gateway-events#identify) event. @@ -275,8 +284,9 @@ Maintaining a stateful application can be difficult when it comes to the amount Intents are bitwise values passed in the `intents` parameter when [Identifying](/docs/events/gateway#identifying) which correlate to a set of related events. For example, the event sent when a guild is created (`GUILD_CREATE`) and when a channel is updated (`CHANNEL_UPDATE`) both require the same `GUILDS (1 << 0)` intent (as listed in the table below). If you do not specify an intent when identifying, you will not receive *any* of the Gateway events associated with that intent. -> info -> Intents are optionally supported on the v6 gateway but required as of v8 +:::info +Intents are optionally supported on the v6 gateway but required as of v8 +::: Two types of intents exist: @@ -434,8 +444,9 @@ Apps that qualify for verification **must** be approved for the privileged inten Before you specify privileged intents in your `IDENTIFY` payload, you must enable the privileged intents your app requires. [Verified apps](https://support-dev.discord.com/hc/en-us/articles/23926564536471-How-Do-I-Get-My-App-Verified) can only use privileged intents *after* they've been approved for them. -> info -> Unverified apps can use privileged intents without approval, but still must enable them in their app's settings. If the app's verification status changes, it will then have to apply for the privileged intent(s). +:::info +Unverified apps can use privileged intents without approval, but still must enable them in their app's settings. If the app's verification status changes, it will then have to apply for the privileged intent(s). +::: In addition to the gateway restrictions described here, Discord's REST API is also affected by Privileged Intents. For example, to use the [List Guild Members](/docs/resources/guild#list-guild-members) endpoint, you must have the `GUILD_MEMBERS` intent enabled for your application. This behavior is independent of whether the intent is set during `IDENTIFY`. @@ -449,8 +460,9 @@ If your app qualifies for [verification](https://support-dev.discord.com/hc/en-u Privileged intents affect which Gateway events your app is permitted to receive. When using **API v8** and above, all intents (privileged and not) must be specified in the `intents` parameter when Identifying. If you pass a privileged intent in the `intents` parameter without configuring it in your app's settings, or being approved for it during verification, your Gateway connection will be closed with a ([`4014` close code](/docs/topics/opcodes-and-status-codes#gateway-gateway-close-event-codes)). -> info -> For **API v6**, you will receive events associated with the privileged intents your app has configured and is authorized to receive *without* passing those intents into the `intents` parameter when Identifying. +:::info +For **API v6**, you will receive events associated with the privileged intents your app has configured and is authorized to receive *without* passing those intents into the `intents` parameter when Identifying. +::: Events associated with the `GUILD_PRESENCES` and `GUILD_MEMBERS` intents are turned off by default regardless of the API version. @@ -466,8 +478,9 @@ HTTP API restrictions are independent of Gateway restrictions, and are unaffecte Any fields affected by the message content intent are noted in the relevant documentation. For example, the `content`, `embeds`, `attachments`, `components`, and `poll` fields in [message objects](/docs/resources/message#message-object) all contain message content and therefore require the intent. -> info -> Like other privileged intents, `MESSAGE_CONTENT` must be approved for your app. After your app is verified, you can apply for the intent from your app's settings within the Developer Portal. You can read more about the message content intent review policy [in the Help Center](https://support-dev.discord.com/hc/en-us/articles/5324827539479). +:::info +Like other privileged intents, `MESSAGE_CONTENT` must be approved for your app. After your app is verified, you can apply for the intent from your app's settings within the Developer Portal. You can read more about the message content intent review policy [in the Help Center](https://support-dev.discord.com/hc/en-us/articles/5324827539479). +::: Apps **without** the intent will receive empty values in fields that contain user-inputted content with a few exceptions: - Content in messages that an app sends @@ -477,8 +490,9 @@ Apps **without** the intent will receive empty values in fields that contain use ## Rate Limiting -> info -> This section refers to Gateway rate limits, not [HTTP API rate limits](/docs/topics/rate-limits) +:::info +This section refers to Gateway rate limits, not [HTTP API rate limits](/docs/topics/rate-limits) +::: Apps can send 120 [gateway events](/docs/events/gateway-events) per [connection](/docs/events/gateway#connections) every 60 seconds, meaning an average of 2 commands per second. Apps that surpass the limit are immediately disconnected from the Gateway. Similar to other rate limits, repeat offenders will have their API access revoked. @@ -496,8 +510,9 @@ When using the plain-text JSON encoding, apps have the option to enable [payload #### Payload Compression -> warn -> If an app is using payload compression, it cannot use [transport compression](/docs/events/gateway#transport-compression). +:::warn +If an app is using payload compression, it cannot use [transport compression](/docs/events/gateway#transport-compression). +::: Payload compression enables optional per-packet compression for *some* events when Discord is sending events over the connection. @@ -568,8 +583,9 @@ Most of a client's state is provided during the initial [Ready](/docs/events/gat As resources continue to be created, updated, and deleted, Gateway events are sent to notify the app of these changes and to provide associated data. To avoid excessive API calls, apps should cache as many relevant resource states as possible, and update them as new events are received. -> info -> For larger apps, client state can grow to be very large. Therefore, we recommend only storing data in memory that are *needed* for the app to operate. In some cases, there isn't a need to cache member information (like roles or permissions) since some events like [MESSAGE_CREATE](/docs/events/gateway-events#message-create) have the full member object included. +:::info +For larger apps, client state can grow to be very large. Therefore, we recommend only storing data in memory that are *needed* for the app to operate. In some cases, there isn't a need to cache member information (like roles or permissions) since some events like [MESSAGE_CREATE](/docs/events/gateway-events#message-create) have the full member object included. +::: An example of state tracking can be considered in the case of an app that wants to track member status: when initially connecting to the Gateway, the app will receive information about the online status of guild members (whether they're online, idle, dnd, or offline). To keep the state updated, the app will track and parse [Presence Update](/docs/events/gateway-events#presence-update) events as they're received, then update the cached member objects accordingly. @@ -581,13 +597,15 @@ When connecting to the gateway as a bot user, guilds that the bot is a part of w As apps grow and are added to an increasing number of guilds, some developers may find it necessary to divide portions of their app's operations across multiple processes. As such, the Gateway implements a method of user-controlled guild sharding which allows apps to split events across a number of Gateway connections. Guild sharding is entirely controlled by an app, and requires no state-sharing between separate connections to operate. While all apps *can* enable sharding, it's not necessary for apps in a smaller number of guilds. -> warn -> Each shard can only support a maximum of 2500 guilds, and apps that are in 2500+ guilds *must* enable sharding. +:::warn +Each shard can only support a maximum of 2500 guilds, and apps that are in 2500+ guilds *must* enable sharding. +::: To enable sharding on a connection, the app should send the `shard` array in the [Identify](/docs/events/gateway-events#identify) payload. The first item in this array should be the zero-based integer value of the current shard, while the second represents the total number of shards. DMs will only be sent to shard 0. -> info -> The [Get Gateway Bot](/docs/events/gateway#get-gateway-bot) endpoint provides a recommended number of shards for your app in the `shards` field +:::info +The [Get Gateway Bot](/docs/events/gateway#get-gateway-bot) endpoint provides a recommended number of shards for your app in the `shards` field +::: To calculate which events will be sent to which shard, the following formula can be used: @@ -681,8 +699,9 @@ The session start limit for these bots will also be increased from 1000 to `max( ## Get Gateway % GET /gateway -> info -> This endpoint does not require authentication. +:::info +This endpoint does not require authentication. +::: Returns an object with a valid WSS URL which the app can use when [Connecting](/docs/events/gateway#connecting) to the Gateway. Apps should cache this value and only call this endpoint to retrieve a new URL when they are unable to properly establish a connection using the cached one. @@ -696,8 +715,9 @@ Returns an object with a valid WSS URL which the app can use when [Connecting](/ ## Get Gateway Bot % GET /gateway/bot -> warn -> This endpoint requires authentication using a valid bot token. +:::warn +This endpoint requires authentication using a valid bot token. +::: Returns an object based on the information in [Get Gateway](/docs/events/gateway#get-gateway), plus additional metadata that can help during the operation of large or [sharded](/docs/events/gateway#sharding) bots. Unlike the [Get Gateway](/docs/events/gateway#get-gateway), this route should not be cached for extended periods of time as the value is not guaranteed to be the same per-call, and changes as the bot joins/leaves guilds. diff --git a/docs/events/webhook-events.mdx b/docs/events/webhook-events.mdx index 2b441603aa..73e97b51bd 100644 --- a/docs/events/webhook-events.mdx +++ b/docs/events/webhook-events.mdx @@ -12,8 +12,9 @@ While [incoming webhooks](/docs/resources/webhook) are triggered by an external To configure webhook events, you'll need to configure your URL and select the events you want your app to receive. -> info -> The steps below walk through subscribing using the developer portal. If you prefer to use the API, you can call [Edit Current Application](/docs/resources/application#edit-current-application). +:::info +The steps below walk through subscribing using the developer portal. If you prefer to use the API, you can call [Edit Current Application](/docs/resources/application#edit-current-application). +::: In your [app's settings](https://discord.com/developers/applications), navigate to the **Webhooks** page from the left-hand sidebar then complete the following: @@ -45,8 +46,9 @@ If either of these are not complete, your Webhook Events URL will not be validat When adding your Webhook Events URL, Discord will send a `POST` request with a `PING` payload with a `type: 0` to your endpoint. Your app is expected to acknowledge the request by returning a `204` response with an empty body. -> info -> You must provide a valid `Content-Type` when responding to `PING`s. See [here](/docs/reference#http-api) for further information. +:::info +You must provide a valid `Content-Type` when responding to `PING`s. See [here](/docs/reference#http-api) for further information. +::: To properly acknowledge a `PING` payload, return a `204` response with no body: @@ -208,7 +210,8 @@ The inner payload is an [entitlement](/docs/resources/entitlement#entitlement-ob #### Quest User Enrollment -> warn -> This event cannot be received by apps at this time. It's documented because it appears on the Webhooks settings page. +:::warn +This event cannot be received by apps at this time. It's documented because it appears on the Webhooks settings page. +::: `QUEST_USER_ENROLLMENT` is sent when a user is added to a Quest on Discord. diff --git a/docs/interactions/application-commands.mdx b/docs/interactions/application-commands.mdx index 5ed6de7678..4edb16cec7 100644 --- a/docs/interactions/application-commands.mdx +++ b/docs/interactions/application-commands.mdx @@ -36,8 +36,9 @@ Application commands are native ways to interact with apps in the Discord client \* `handler` can only be set for application commands of type `PRIMARY_ENTRY_POINT` for applications with the `EMBEDDED` flag (i.e. applications that have an Activity). -> danger -> `default_permission` will soon be deprecated. You can instead set `default_member_permissions` to `"0"` to disable the command for everyone except admins by default, and/or use `contexts` to disable globally-scoped commands inside of DMs with your app +:::danger +`default_permission` will soon be deprecated. You can instead set `default_member_permissions` to `"0"` to disable the command for everyone except admins by default, and/or use `contexts` to disable globally-scoped commands inside of DMs with your app +::: ###### Application Command Types @@ -50,8 +51,9 @@ Application commands are native ways to interact with apps in the Discord client ###### Application Command Option Structure -> warn -> Required `options` must be listed before optional options +:::warn +Required `options` must be listed before optional options +::: | Field | Type | Description | Valid Option Types | |----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------| @@ -74,8 +76,9 @@ Application commands are native ways to interact with apps in the Discord client \*\* `autocomplete` may not be set to true if `choices` are present. -> info -> Options using `autocomplete` are not confined to only use choices given by the application. +:::info +Options using `autocomplete` are not confined to only use choices given by the application. +::: ###### Application Command Option Type @@ -95,8 +98,9 @@ Application commands are native ways to interact with apps in the Discord client ###### Application Command Option Choice Structure -> info -> If you specify `choices` for an option, they are the **only** valid values for a user to pick +:::info +If you specify `choices` for an option, they are the **only** valid values for a user to pick +::: | Field | Type | Description | |---------------------|-----------------------------------------------------------------------|---------------------------------------------------------------------------------------------| @@ -126,8 +130,9 @@ If your application does not require a bot user in the guild for its commands to ## Registering a Command -> info -> Commands can only be registered via HTTP endpoint. +:::info +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. @@ -152,8 +157,9 @@ An app can have the following number of commands: For all command types except `PRIMARY_ENTRY_POINT`, you can have the same amount of guild-specific commands per guild. -> danger -> There is a global rate limit of 200 application command creates per day, per guild +:::danger +There is a global rate limit of 200 application command creates per day, per guild +::: ### Making a Global Command @@ -267,8 +273,9 @@ Commands have two sets of contexts on the [application command object](/docs/int Details for both types of command contexts are in the sections below. -> info -> Contexts are distinct from, and do not affect, any [command permissions](/docs/interactions/application-commands#permissions) for apps installed to a server. +:::info +Contexts are distinct from, and do not affect, any [command permissions](/docs/interactions/application-commands#permissions) for apps installed to a server. +::: ### Installation Context @@ -290,8 +297,9 @@ By default, `contexts` includes all interaction context types. 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 also be updated by users in the client if they have the necessary permissions. -> warn -> Command permissions can only be updated using a [Bearer token](/docs/topics/oauth2#client-credentials-grant). Authenticating with a bot token will result in an error. +:::warn +Command permissions can only be updated using a [Bearer token](/docs/topics/oauth2#client-credentials-grant). Authenticating with a bot token will result in an error. +::: A command's current permissions can be retrieved using the [`GET /applications/\{application.id}/guilds/\{guild.id}/commands/\{command.id}/permissions`](/docs/interactions/application-commands#get-application-command-permissions) endpoint. The response will include an array called `permissions` with associated IDs and permission types. @@ -352,8 +360,9 @@ To allow for fine-tuned access to commands, application command permissions are Similar to how threads [inherit user and role permissions from the parent channel](/docs/topics/threads#permissions), any command permissions for a channel will apply to the threads it contains. -> info -> 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. +:::info +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. +::: ###### Using Default Permissions @@ -418,8 +427,9 @@ Slash commands—the `CHAT_INPUT` type—are a type of application command. They Slash commands can also have groups and subcommands to further organize commands. More on those later. -> warn -> 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. When [localization fields](/docs/interactions/application-commands#localization) are present, only the longest localization for each field (including the default value) is counted towards the size limit. +:::warn +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. When [localization fields](/docs/interactions/application-commands#localization) are present, only the longest localization for each field (including the default value) is counted towards the size limit. +::: ###### Example Slash Command @@ -511,8 +521,9 @@ When someone uses a slash command, your application will receive an interaction: ## Subcommands and Subcommand Groups -> warn -> Currently, subcommands and subcommand groups all appear at the top level in the command explorer. This may change in the future to include them as nested autocomplete options. +:::warn +Currently, subcommands and subcommand groups all appear at the top level in the command explorer. This may change in the future to include them as nested autocomplete options. +::: For those developers looking to make more organized and complex groups of commands, look no further than subcommands and groups. @@ -522,8 +533,9 @@ For those developers looking to make more organized and complex groups of comman These are not enforced rules. You are free to use subcommands and groups however you'd like; it's just how we think about them. -> danger -> Using subcommands or subcommand groups will make your base command unusable. You can't send the base `/permissions` command as a valid command if you also have `/permissions add | remove` as subcommands or subcommand groups +:::danger +Using subcommands or subcommand groups will make your base command unusable. You can't send the base `/permissions` command as a valid command if you also have `/permissions add | remove` as subcommands or subcommand groups +::: We support nesting one level deep within a group, meaning your top level command can contain subcommand groups, and those groups can contain subcommands. **That is the only kind of nesting supported.** Here's some visual examples: @@ -791,11 +803,13 @@ And, done! The JSON looks a bit complicated, but what we've ended up with is a s User commands are application commands that appear on the context menu (right click or tap) of users. They're a great way to surface quick actions for your app that target users. They don't take any arguments, and will return the user on whom you clicked or tapped in the interaction response. -> warn -> A user must have permission to send text messages in the channel they invoke a user command in. If they don't have this permission, they will receive a 'Permission Denied' error from the interaction. +:::warn +A user must have permission to send text messages in the channel they invoke a user command in. If they don't have this permission, they will receive a 'Permission Denied' error from the interaction. +::: -> danger -> The `description` field is not allowed when creating user commands. However, to avoid breaking changes to data models, `description` will be an **empty string** (instead of `null`) when fetching commands. +:::danger +The `description` field is not allowed when creating user commands. However, to avoid breaking changes to data models, `description` will be an **empty string** (instead of `null`) when fetching commands. +::: ###### Example User Command @@ -885,8 +899,9 @@ When someone uses a user command, your application will receive an interaction: Message commands are application commands that appear on the context menu (right click or tap) of messages. They're a great way to surface quick actions for your app that target messages. They don't take any arguments, and will return the message on whom you clicked or tapped in the interaction response. -> danger -> The `description` field is not allowed when creating message commands. However, to avoid breaking changes to data models, `description` will be an **empty string** (instead of `null`) when fetching commands. +:::danger +The `description` field is not allowed when creating message commands. However, to avoid breaking changes to data models, `description` will be an **empty string** (instead of `null`) when fetching commands. +::: ###### Example Message Command @@ -1012,8 +1027,9 @@ Autocomplete interactions allow your application to dynamically return option su An autocomplete interaction **can return partial data** for option values. Your application will receive partial data for any existing user input, as long as that input passes client-side validation. For example, you may receive partial strings, but not invalid numbers. The option the user is currently typing will be sent with a `focused: true` boolean field and options the user has already filled will also be sent but without the `focused` field. This is a special case where options that are otherwise required might not be present, due to the user not having filled them yet. -> warn -> This validation is **client-side only**. +:::warn +This validation is **client-side only**. +::: ```json { @@ -1079,9 +1095,9 @@ An application command furnished with localizations might look like this: For application commands, there are built-in fallbacks in case a user's locale isn't present in the localizations. If the fallback locale is also missing, it will use the default. -> warn -> You should make sure to include your default value in its proper locale key, otherwise it may use a fallback value unexpectedly. For example, if your default value is `en-US`, but you don't specify the `en-US` value in your localizations, users with `en-US` selected will see the `en-GB` value if it's specified. -> For example, if you have a command with the default name "color", and your localizations specify only the `en-GB` value as "colour", users in the `en-US` locale will see "colour" because the `en-US` key is missing. +:::warn +You should make sure to include your default value in its proper locale key, otherwise it may use a fallback value unexpectedly. For example, if your default value is `en-US`, but you don't specify the `en-US` value in your localizations, users with `en-US` selected will see the `en-GB` value if it's specified. For example, if you have a command with the default name "color", and your localizations specify only the `en-GB` value as "colour", users in the `en-US` locale will see "colour" because the `en-US` key is missing. +::: | Locale | Fallback | |--------|----------| @@ -1122,8 +1138,9 @@ Locale is determined by looking at the `X-Discord-Locale` header, then the `Acce A command that contains age-restricted content should have the [`nsfw` field](/docs/interactions/application-commands#application-command-object-application-command-structure) set to `true` upon creation or update. Marking a command as age-restricted will limit who can see and access the command, and from which channels. -> warn -> Apps with [discovery enabled](https://support-dev.discord.com/hc/en-us/articles/9489299950487) (which is required to appear in the App Directory) cannot contain any age-restricted commands or content. +:::warn +Apps with [discovery enabled](https://support-dev.discord.com/hc/en-us/articles/9489299950487) (which is required to appear in the App Directory) cannot contain any age-restricted commands or content. +::: ### Using Age-Restricted Commands @@ -1135,13 +1152,15 @@ Details about accessing and using age-restricted commands is in [the Help Center ### Endpoints -> info -> For authorization, all endpoints take either a [bot token](/docs/reference#authentication) or [client credentials token](/docs/topics/oauth2#client-credentials-grant) for your application +:::info +For authorization, all endpoints take either a [bot token](/docs/reference#authentication) or [client credentials token](/docs/topics/oauth2#client-credentials-grant) for your application +::: ## Get Global Application Commands % GET /applications/\{application.id/docs/resources/application#application-object\}/commands -> warn -> The objects returned by this endpoint may be augmented with [additional fields if localization is active](/docs/interactions/application-commands#retrieving-localized-commands). +:::warn +The objects returned by this endpoint may be augmented with [additional fields if localization is active](/docs/interactions/application-commands#retrieving-localized-commands). +::: Fetch all of the global commands for your application. Returns an array of [application command](/docs/interactions/application-commands#application-command-object) objects. @@ -1153,8 +1172,9 @@ Fetch all of the global commands for your application. Returns an array of [appl ## Create Global Application Command % POST /applications/\{application.id/docs/resources/application#application-object\}/commands -> warn -> Creating a command with the same name as an existing command for your application will overwrite the old command. +:::warn +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 does not already exist, or a `200` if it does (in which case the previous command will be overwritten). Both responses include an [application command](/docs/interactions/application-commands#application-command-object) object. @@ -1181,8 +1201,9 @@ Fetch a global command for your application. Returns an [application command](/d ## Edit Global Application Command % PATCH /applications/\{application.id/docs/resources/application#application-object\}/commands/\{command.id/docs/interactions/application-commands#application-command-object\} -> info -> All parameters for this endpoint are optional. +:::info +All parameters for this endpoint are optional. +::: Edit a global command. Returns `200` and an [application command](/docs/interactions/application-commands#application-command-object) object. All fields are optional, but any fields provided will entirely overwrite the existing values of those fields. @@ -1210,13 +1231,15 @@ Deletes a global command. Returns `204 No Content` on success. Takes a list of application commands, overwriting the existing global command list for this application. Returns `200` and a list of [application command](/docs/interactions/application-commands#application-command-object) objects. Commands that do not already exist will count toward daily application command create limits. -> danger -> This will overwrite **all** types of application commands: slash commands, user commands, and message commands. +:::danger +This will overwrite **all** types of application commands: slash commands, user commands, and message commands. +::: ## Get Guild Application Commands % GET /applications/\{application.id/docs/resources/application#application-object\}/guilds/\{guild.id/docs/resources/guild#guild-object\}/commands -> warn -> The objects returned by this endpoint may be augmented with [additional fields if localization is active](/docs/interactions/application-commands#retrieving-localized-commands). +:::warn +The objects returned by this endpoint may be augmented with [additional fields if localization is active](/docs/interactions/application-commands#retrieving-localized-commands). +::: Fetch all of the guild commands for your application for a specific guild. Returns an array of [application command](/docs/interactions/application-commands#application-command-object) objects. @@ -1228,8 +1251,9 @@ Fetch all of the guild commands for your application for a specific guild. Retur ## Create Guild Application Command % POST /applications/\{application.id/docs/resources/application#application-object\}/guilds/\{guild.id/docs/resources/guild#guild-object\}/commands -> danger -> Creating a command with the same name as an existing command for your application will overwrite the old command. +:::danger +Creating a command with the same name as an existing command for your application will overwrite the old command. +::: Create a new guild command. New guild commands will be available in the guild immediately. Returns `201` if a command with the same name does not already exist, or a `200` if it does (in which case the previous command will be overwritten). Both responses include an [application command](/docs/interactions/application-commands#application-command-object) object. @@ -1253,8 +1277,9 @@ Fetch a guild command for your application. Returns an [application command](/do ## Edit Guild Application Command % PATCH /applications/\{application.id/docs/resources/application#application-object}/guilds/\{guild.id/docs/resources/guild#guild-object\}/commands/\{command.id/docs/interactions/application-commands#application-command-object\} -> info -> All parameters for this endpoint are optional. +:::info +All parameters for this endpoint are optional. +::: Edit a guild command. Updates for guild commands will be available immediately. Returns `200` and an [application command](/docs/interactions/application-commands#application-command-object) object. All fields are optional, but any fields provided will entirely overwrite the existing values of those fields. @@ -1279,8 +1304,9 @@ Delete a guild command. Returns `204 No Content` on success. Takes a list of application commands, overwriting the existing command list for this application for the targeted guild. Returns `200` and a list of [application command](/docs/interactions/application-commands#application-command-object) objects. -> danger -> This will overwrite **all** types of application commands: slash commands, user commands, and message commands. +:::danger +This will overwrite **all** types of application commands: slash commands, user commands, and message commands. +::: ###### JSON Params @@ -1310,18 +1336,21 @@ Fetches permissions for a specific command for your application in a guild. Retu ## Edit Application Command Permissions % PUT /applications/\{application.id/docs/resources/application#application-object\}/guilds/\{guild.id/docs/resources/guild#guild-object\}/commands/\{command.id/docs/interactions/application-commands#application-command-object\}/permissions -> warn -> This endpoint will overwrite existing permissions for the command in that guild +:::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 and returns a [guild application command permissions](/docs/interactions/application-commands#application-command-permissions-object-guild-application-command-permissions-structure) object. Fires an [Application Command Permissions Update](/docs/events/gateway-events#application-command-permissions-update) Gateway event. You can add up to 100 permission overwrites for a command. -> info -> This endpoint requires authentication with a Bearer token that has permission to manage the guild and its roles. For more information, read above about [application command permissions](/docs/interactions/application-commands#permissions). +:::info +This endpoint requires authentication with a Bearer token that has permission to manage the guild and its roles. For more information, read above about [application command permissions](/docs/interactions/application-commands#permissions). +::: -> warn -> Deleting or renaming a command will permanently delete all permissions for the command +:::warn +Deleting or renaming a command will permanently delete all permissions for the command +::: ###### JSON Params @@ -1331,5 +1360,6 @@ You can add up to 100 permission overwrites for a command. ## Batch Edit Application Command Permissions % PUT /applications/\{application.id/docs/resources/application#application-object\}/guilds/\{guild.id/docs/resources/guild#guild-object\}/commands/permissions -> danger -> This endpoint has been disabled with [updates to command permissions (Permissions v2)](/docs/change-log#updated-command-permissions). Instead, you can [edit each application command permissions](/docs/interactions/application-commands#edit-application-command-permissions) (though you should be careful to handle any potential [rate limits](/docs/topics/rate-limits)). +:::danger +This endpoint has been disabled with [updates to command permissions (Permissions v2)](/docs/change-log#updated-command-permissions). Instead, you can [edit each application command permissions](/docs/interactions/application-commands#edit-application-command-permissions) (though you should be careful to handle any potential [rate limits](/docs/topics/rate-limits)). +::: diff --git a/docs/interactions/message-components.md b/docs/interactions/message-components.md index 5eab856122..87600e4074 100644 --- a/docs/interactions/message-components.md +++ b/docs/interactions/message-components.md @@ -474,8 +474,9 @@ The payloads for the select menu components are detailed in the [select menu str The `resolved` object is included in interaction payloads for user, role, mentionable, and channel select menu components. `resolved` contains a nested object with additional details about the selected options with the key of the resource type—`users`, `roles`, `channels`, and `members`. -> info -> `members` and `users` may both be present in the `resolved` object when a user is selected (in either a user select or mentionable select). +:::info +`members` and `users` may both be present in the `resolved` object when a user is selected (in either a user select or mentionable select). +::: ###### Example Resolved Object diff --git a/docs/interactions/overview.mdx b/docs/interactions/overview.mdx index 71c97af39b..cfecfefd1c 100644 --- a/docs/interactions/overview.mdx +++ b/docs/interactions/overview.mdx @@ -80,8 +80,9 @@ If either of these are not complete, your Interactions Endpoint URL will not be When adding your Interactions Endpoint URL, Discord will send a `POST` request with a `PING` payload with a `type: 1` to your endpoint. Your app is expected to acknowledge the request by returning a `200` response with a `PONG` payload (which has the same `type: 1`). Details about interaction responses are in the [Receiving and Responding documentation](/docs/interactions/receiving-and-responding). -> info -> You must provide a valid `Content-Type` when responding to `PING`s. See [here](/docs/reference#http-api) for further information. +:::info +You must provide a valid `Content-Type` when responding to `PING`s. See [here](/docs/reference#http-api) for further information. +::: To properly acknowledge a `PING` payload, return a `200` response with a payload of `type: 1`: diff --git a/docs/interactions/receiving-and-responding.mdx b/docs/interactions/receiving-and-responding.mdx index 74ffea6a00..2d9c0e825d 100644 --- a/docs/interactions/receiving-and-responding.mdx +++ b/docs/interactions/receiving-and-responding.mdx @@ -89,8 +89,9 @@ While the `data` field is guaranteed to be present for all [interaction types](/ ###### Application Command Data Structure -> info -> Sent in `APPLICATION_COMMAND` and `APPLICATION_COMMAND_AUTOCOMPLETE` interactions. +:::info +Sent in `APPLICATION_COMMAND` and `APPLICATION_COMMAND_AUTOCOMPLETE` interactions. +::: | Field | Type | Description | |------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -124,8 +125,9 @@ While the `data` field is guaranteed to be present for all [interaction types](/ ###### Resolved Data Structure -> info -> If data for a Member is included, data for its corresponding User will also be included. +:::info +If data for a Member is included, data for its corresponding User will also be included. +::: | Field | Type | Description | |---------------|------------------------------------------------------------------------------------------|---------------------------------| @@ -158,8 +160,9 @@ All options have names, and an option can either be a parameter and input value- This is sent on the [message object](/docs/resources/message#message-object) when the message is a response to an Interaction without an existing message. -> info -> This means responses to [Message Components](/docs/interactions/message-components#) do not include this property, instead including a [message reference](/docs/resources/message#message-reference-structure) object as components _always_ exist on preexisting messages. +:::info +This means responses to [Message Components](/docs/interactions/message-components#) do not include this property, instead including a [message reference](/docs/resources/message#message-reference-structure) object as components _always_ exist on preexisting messages. +::: ###### Message Interaction Structure @@ -201,8 +204,9 @@ Now that you've gotten the data from the user, it's time to respond to them. Interactions--both receiving and responding--are webhooks under the hood. So responding to an Interaction is just like sending a webhook request! -> info -> Interaction responses have the same header requirements as normal HTTP API requests. See [here](/docs/reference#http-api) for further information. +:::info +Interaction responses have the same header requirements as normal HTTP API requests. See [here](/docs/reference#http-api) for further information. +::: There are a number of ways you can respond to an interaction: @@ -263,8 +267,9 @@ Not all message fields are currently supported. ###### Modal -> warn -> Support for components in modals is currently limited to type 4 (Text Input). +:::warn +Support for components in modals is currently limited to type 4 (Text Input). +::: | Field | Type | Description | |------------|---------------------------------------------------------------|----------------------------------------------------------------| @@ -272,8 +277,9 @@ Not all message fields are currently supported. | title | string | Title of the popup modal, max 45 characters | | components | array of [components](/docs/interactions/message-components#) | Between 1 and 5 (inclusive) components that make up the modal | -> warn -> If your application responds with user data, you should use [`allowed_mentions`](/docs/resources/message#allowed-mentions-object) to filter which mentions in the content actually ping. +:::warn +If your application responds with user data, you should use [`allowed_mentions`](/docs/resources/message#allowed-mentions-object) to filter which mentions in the content actually ping. +::: ## Interaction Callback @@ -297,8 +303,9 @@ json = { r = requests.post(url, json=json) ``` -> info -> Interaction `tokens` are valid for **15 minutes** and can be used to send followup messages but you **must send an initial response within 3 seconds of receiving the event**. If the 3 second deadline is exceeded, the token will be invalidated. +:::info +Interaction `tokens` are valid for **15 minutes** and can be used to send followup messages but you **must send an initial response within 3 seconds of receiving the event**. If the 3 second deadline is exceeded, the token will be invalidated. +::: If you receive interactions over HTTP, your server can also respond to the received `POST` request. You'll want to respond with a `200` status code (if everything went well), as well as specifying a `type` and `data`, which is an [Interaction Response](/docs/interactions/receiving-and-responding#interaction-response-object) object: @@ -370,15 +377,17 @@ Sometimes, your bot will want to send followup messages to a user after respondi - [`POST /webhooks//`](/docs/interactions/receiving-and-responding#create-followup-message) to send a new followup message - [`PATCH /webhooks///messages/`](/docs/interactions/receiving-and-responding#edit-followup-message) to edit a message sent with that `token` -> info -> Interactions webhooks share the same rate limit properties as normal webhooks. +:::info +Interactions webhooks share the same rate limit properties as normal webhooks. +::: Interaction tokens are valid for **15 minutes**, meaning you can respond to an interaction within that amount of time. ### Endpoints -> info -> The endpoints below are not bound to the application's [Global Rate Limit](/docs/topics/rate-limits#global-rate-limit). +:::info +The endpoints below are not bound to the application's [Global Rate Limit](/docs/topics/rate-limits#global-rate-limit). +::: ## Create Interaction Response % POST /interactions/\{interaction.id/docs/interactions/receiving-and-responding#interaction-object\}/\{interaction.token/docs/interactions/receiving-and-responding#interaction-object\}/callback @@ -407,8 +416,9 @@ Deletes the initial Interaction response. Returns `204 No Content` on success. ## Create Followup Message % POST /webhooks/\{application.id/docs/resources/application#application-object\}/\{interaction.token/docs/interactions/receiving-and-responding#interaction-object\} -> info -> Apps are limited to 5 followup messages per interaction if it was initiated from a user-installed app and isn't installed in the server (meaning the [authorizing integration owners object](/docs/interactions/receiving-and-responding#interaction-object-authorizing-integration-owners-object) only contains `USER_INSTALL`) +:::info +Apps are limited to 5 followup messages per interaction if it was initiated from a user-installed app and isn't installed in the server (meaning the [authorizing integration owners object](/docs/interactions/receiving-and-responding#interaction-object-authorizing-integration-owners-object) only contains `USER_INSTALL`) +::: Create a followup message for an Interaction. Functions the same as [Execute Webhook](/docs/resources/webhook#execute-webhook), but `wait` is always true. The `thread_id`, `avatar_url`, and `username` parameters are not supported when using this endpoint for interaction followups. You can use the `EPHEMERAL` [message flag](/docs/resources/message#message-object-message-flags) `1 << 6` (64) to send a message that only the user can see. diff --git a/docs/monetization/enabling-monetization.mdx b/docs/monetization/enabling-monetization.mdx index 1a7c18950d..3642f70fee 100644 --- a/docs/monetization/enabling-monetization.mdx +++ b/docs/monetization/enabling-monetization.mdx @@ -57,8 +57,9 @@ Let's set up Team Payouts so you can get paid! Discord processes all payouts thr #### If You are Based Outside of the United States, European Union, or United Kingdom -> info -> Premium Apps is not currently available outside of these regions. These features will be made available to more regions soon. +:::info +Premium Apps is not currently available outside of these regions. These features will be made available to more regions soon. +::: For more information, read the [Premium Apps Payouts](https://support-dev.discord.com/hc/articles/17299902720919) Help Center article. diff --git a/docs/monetization/implementing-app-subscriptions.mdx b/docs/monetization/implementing-app-subscriptions.mdx index b015ce301e..3be691aa7f 100644 --- a/docs/monetization/implementing-app-subscriptions.mdx +++ b/docs/monetization/implementing-app-subscriptions.mdx @@ -31,8 +31,9 @@ When creating subscriptions, you will need to choose between user or guild subsc Because entitlements are granted indefinitely and don't update on renewal or cancellation, you can use subscription events to track the lifecycle of a subscription. -> info -> This is not a complete list of when events may occur. You should use the presence of an entitlement to determine if a user has access to your premium features. The Subscription API and related events are intended for reporting and lifecycle management purposes and **should not be used as the source of truth of whether a user has access to your premium features**. +:::info +This is not a complete list of when events may occur. You should use the presence of an entitlement to determine if a user has access to your premium features. The Subscription API and related events are intended for reporting and lifecycle management purposes and **should not be used as the source of truth of whether a user has access to your premium features**. +::: | Event Name | Subscription Behavior | Updated Fields | |-----------------------|--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------| @@ -184,8 +185,9 @@ Once the user's current subscription expires on `subscription.current_period_end ## Using the Subscription API -> info -> When implementing monetization, [Entitlements](/docs/resources/entitlement) should be considered the source of truth for a user's access to a specific SKU. The Subscription API is intended for reporting and lifecycle management purposes that happen outside the flow of a user's interaction with your app. +:::info +When implementing monetization, [Entitlements](/docs/resources/entitlement) should be considered the source of truth for a user's access to a specific SKU. The Subscription API is intended for reporting and lifecycle management purposes that happen outside the flow of a user's interaction with your app. +::: You can use the [Subscription API](/docs/resources/subscription) to check on the status of your app subscriptions. This API allows you to list subscriptions by user for reporting purposes and to check on the status of subscriptions without having to access entitlements directly. @@ -203,8 +205,9 @@ You can test your implementation by [creating](/docs/resources/entitlement#creat This method will not let you test out the full payment flow in Discord but will allow you to test your app's behavior when a user is subscribed or unsubscribed. See [Using Live Entitlements](/docs/monetization/implementing-app-subscriptions#using-live-entitlements) if you'd like to see the full payment flow. -> info -> Test Entitlements do not have a `starts_at` or `ends_at` field as they are valid until they are deleted. +:::info +Test Entitlements do not have a `starts_at` or `ends_at` field as they are valid until they are deleted. +::: ### Using Live Entitlements @@ -212,5 +215,6 @@ If you'd like to test the full payment flow for your app, you can do so by inter After checkout, you will have a live subscription. This subscription will renew until canceled and can be used in testing subscription renewals in your app. If you cancel this subscription, it will remain an active entitlement until the end of the subscription billing period, represented by the `period_ends_at` field on the [Subscription](/docs/resources/subscription#subscription-object). -> info -> You can only delete entitlements created using the [create entitlement](/docs/resources/entitlement#create-test-entitlement) endpoint. If you need to toggle access to your premium features during your development process, it is best to use Test Entitlements. \ No newline at end of file +:::info +You can only delete entitlements created using the [create entitlement](/docs/resources/entitlement#create-test-entitlement) endpoint. If you need to toggle access to your premium features during your development process, it is best to use Test Entitlements. +::: \ No newline at end of file diff --git a/docs/monetization/implementing-one-time-purchases.md b/docs/monetization/implementing-one-time-purchases.md index a4a3803df1..8ab13209c0 100644 --- a/docs/monetization/implementing-one-time-purchases.md +++ b/docs/monetization/implementing-one-time-purchases.md @@ -91,15 +91,17 @@ If you are using the [Embedded App SDK](/docs/developer-tools/embedded-app-sdk) ## Testing Your One-Time Purchase Implementation -> warn -> The method of testing purchases for One-Time Purchases differs from the method for App Subscriptions. **Do NOT use Test Entitlements for One-Time Purchases.** +:::warn +The method of testing purchases for One-Time Purchases differs from the method for App Subscriptions. **Do NOT use Test Entitlements for One-Time Purchases.** +::: ### Using Application Test Mode While in Application Test Mode, you can freely make "purchases" of One-Time Purchase SKUs tied to your application. That means you can test buying your consumable and durable items by going through the In-App Purchase flow without any credit card charges. -> info -> You still need to have a valid payment method on file to "purchase" SKUs in Application Test Mode. It just won't be charged at checkout. +:::info +You still need to have a valid payment method on file to "purchase" SKUs in Application Test Mode. It just won't be charged at checkout. +::: To enable it, first, make sure you have a payment method on file in `User Settings -> Billing` and then: @@ -115,6 +117,7 @@ You can now navigate to your Store page and purchase your one-time purchase item The entitlements tied to items purchased in Application Test Mode can be identified by entitlements with a `type` value of 4 to represent `TEST_MODE_PURCHASE`. -> warn -> The "Go To SKU" button does not currently work. To purchase your SKU in test mode, go to your Store page. +:::warn +The "Go To SKU" button does not currently work. To purchase your SKU in test mode, go to your Store page. +::: diff --git a/docs/monetization/managing-skus.mdx b/docs/monetization/managing-skus.mdx index 3da9676c73..4100eb6a62 100644 --- a/docs/monetization/managing-skus.mdx +++ b/docs/monetization/managing-skus.mdx @@ -34,8 +34,9 @@ There are some limitations to the number of SKUs you can create: - You can offer either user subscription SKUs or guild subscription SKUs, but not both simultaneously. - SKU prices must be selected from the list of available prices. -> info -> If you need more SKUs than the 50 limit, consider creating a consumable in-app currency SKU that can be used to purchase items that are tracked in your app. +:::info +If you need more SKUs than the 50 limit, consider creating a consumable in-app currency SKU that can be used to purchase items that are tracked in your app. +::: --- @@ -65,10 +66,11 @@ Subscription SKUs are automatically charged each month unless canceled. Changing To set an icon using a standard Unicode emoji, enter the emoji in the `Unicode Emoji or Custom Emoji Name` field. -> info -> Using an emoji keyboard can make it easier to pick an icon to display alongside your SKU benefit. -> MacOS: `control + command + space bar` -> Windows: `Windows + .` +:::info +Using an emoji keyboard can make it easier to pick an icon to display alongside your SKU benefit. +MacOS: `control + command + space bar` +Windows: `Windows + .` +::: ![Set a unicode emoji](images/sku-unicode.png) @@ -79,8 +81,9 @@ To use a custom emoji, set a value for both fields: - Name of your custom emoji - ID of the custom emoji -> info -> You can find the ID of the emoji in the Discord app by escaping the emoji in a message with a backslash character `\`. For example, `\:uwu:` will render with the name and ID of the emoji. +:::info +You can find the ID of the emoji in the Discord app by escaping the emoji in a message with a backslash character `\`. For example, `\:uwu:` will render with the name and ID of the emoji. +::: ![Set a custom emoji](images/sku-custom.png) @@ -111,8 +114,9 @@ You can only make API calls or use the Embedded App SDK to grant entitlements fo ### Unpublishing a SKU -> warn -> **Danger:** Unpublishing a SKU can affect your users' existing subscriptions and entitlements +:::warn +**Danger:** Unpublishing a SKU can affect your users' existing subscriptions and entitlements +::: Unpublishing a SKU removes it from the Store and the API, making it unavailable for purchase. @@ -124,8 +128,9 @@ Unpublishing a SKU has the following effects: ### Deleting a SKU -> warn -> **Danger:** Deleting a SKU can affect your users' existing subscriptions and entitlements +:::warn +**Danger:** Deleting a SKU can affect your users' existing subscriptions and entitlements +::: Deletes a SKU in the UI and makes it unavailable for publishing. Deleted SKUs are still listed when calling [List SKUs](/docs/resources/sku#list-skus) in the API. @@ -163,8 +168,9 @@ After you've published your SKUs, you are ready to start implementing your premi Users can access an app's Store page from the Bot User's profile in a server. This allows users to view an available subscription and one-time purchases, select a subscription to view its perks, benefits, and details, and make a purchase directly from an app's Store page. -> info -> Only subscriptions and items that have been published to the Store will be visible to users on the Store page. +:::info +Only subscriptions and items that have been published to the Store will be visible to users on the Store page. +::: #### Accessing your Store page from a Bot User's Profile ![Accessing the store as a user](images/botuser-profile.png) diff --git a/docs/policies-and-agreements/developer-policy.md b/docs/policies-and-agreements/developer-policy.md index 04774bd7e9..25da6ab0ac 100644 --- a/docs/policies-and-agreements/developer-policy.md +++ b/docs/policies-and-agreements/developer-policy.md @@ -4,8 +4,9 @@ sidebar_label: Developer Policy # Discord Developer Policy -> info -> We’re updating our Developer Terms of Service and Developer Policy, effective July 8, 2024. Please review the updated Policy below and Terms [here](/docs/policies-and-agreements/developer-terms-of-service). If you access or use the APIs on or after July 8, 2024, it means you agree to the updated Policy and Terms. Until then, the current [Developer Terms of Service](https://github.com/discord/discord-api-docs/blob/e5cd463cd1412df2e55fce8ecb81e7d1ed5755b0/docs/policies_and_agreements/Developer_Terms_of_Service.md) and [Developer Policy](https://github.com/discord/discord-api-docs/blob/e5cd463cd1412df2e55fce8ecb81e7d1ed5755b0/docs/policies_and_agreements/Developer_Policy.md) will apply. +:::info +We’re updating our Developer Terms of Service and Developer Policy, effective July 8, 2024. Please review the updated Policy below and Terms [here](/docs/policies-and-agreements/developer-terms-of-service). If you access or use the APIs on or after July 8, 2024, it means you agree to the updated Policy and Terms. Until then, the current [Developer Terms of Service](https://github.com/discord/discord-api-docs/blob/e5cd463cd1412df2e55fce8ecb81e7d1ed5755b0/docs/policies_and_agreements/Developer_Terms_of_Service.md) and [Developer Policy](https://github.com/discord/discord-api-docs/blob/e5cd463cd1412df2e55fce8ecb81e7d1ed5755b0/docs/policies_and_agreements/Developer_Policy.md) will apply. +::: ## Effective date: July 8, 2024 diff --git a/docs/policies-and-agreements/developer-terms-of-service.md b/docs/policies-and-agreements/developer-terms-of-service.md index 2da0c02b78..28928081e2 100644 --- a/docs/policies-and-agreements/developer-terms-of-service.md +++ b/docs/policies-and-agreements/developer-terms-of-service.md @@ -4,8 +4,9 @@ sidebar_label: Developer Terms of Service # Discord Developer Terms of Service -> info -> We’re updating our Developer Terms of Service and Developer Policy, effective July 8, 2024. Please review the updated Terms below and Policy [here](/docs/policies-and-agreements/developer-policy). If you access or use the APIs on or after July 8, 2024, it means you agree to the updated Terms and Policy. Until then, the current [Developer Terms of Service](https://github.com/discord/discord-api-docs/blob/e5cd463cd1412df2e55fce8ecb81e7d1ed5755b0/docs/policies_and_agreements/Developer_Terms_of_Service.md) and [Developer Policy](https://github.com/discord/discord-api-docs/blob/e5cd463cd1412df2e55fce8ecb81e7d1ed5755b0/docs/policies_and_agreements/Developer_Policy.md) will apply. +:::info +We’re updating our Developer Terms of Service and Developer Policy, effective July 8, 2024. Please review the updated Terms below and Policy [here](/docs/policies-and-agreements/developer-policy). If you access or use the APIs on or after July 8, 2024, it means you agree to the updated Terms and Policy. Until then, the current [Developer Terms of Service](https://github.com/discord/discord-api-docs/blob/e5cd463cd1412df2e55fce8ecb81e7d1ed5755b0/docs/policies_and_agreements/Developer_Terms_of_Service.md) and [Developer Policy](https://github.com/discord/discord-api-docs/blob/e5cd463cd1412df2e55fce8ecb81e7d1ed5755b0/docs/policies_and_agreements/Developer_Policy.md) will apply. +::: ## Effective date: July 8, 2024 diff --git a/docs/quick-start/getting-started.mdx b/docs/quick-start/getting-started.mdx index 8d9af3fc0d..43e2a4d1de 100644 --- a/docs/quick-start/getting-started.mdx +++ b/docs/quick-start/getting-started.mdx @@ -6,8 +6,9 @@ sidebar_label: Getting Started [Discord apps](/docs/quick-start/overview-of-apps) let you customize and extend Discord using a collection of APIs and interactive features. This guide will walk you through building your first Discord app using JavaScript and by the end you'll have an app that uses slash commands, sends messages, and responds to component interactions. -> info -> If you're interested in building a game or social experience in an iframe, you can follow the tutorial for [building an Activity](/docs/activities/building-an-activity) +:::info +If you're interested in building a game or social experience in an iframe, you can follow the tutorial for [building an Activity](/docs/activities/building-an-activity) +::: We'll be building a Discord app that lets users play rock-paper-scissors (with 7 choices instead of 3). This guide is beginner-focused, but it assumes a basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics). @@ -38,8 +39,9 @@ To make the user flow a bit more explicit: Before we get started, you'll need to set up your local environment and get the project code from the [sample app repository](https://github.com/discord/discord-example-app). -> info -> We'll be developing our app locally with a little help from [ngrok](https://ngrok.com/), but you can use your preferred development environment. +:::info +We'll be developing our app locally with a little help from [ngrok](https://ngrok.com/), but you can use your preferred development environment. +::: If you don't have [NodeJS](https://nodejs.org/en/download/) installed, install that first. @@ -95,8 +97,9 @@ After you create your app, you'll land on the **General Information** page of th We'll need to set up and fetch a few sensitive values for your app, like its token and ID. -> warn -> Your token is used to authorize API requests and carry your app's permissions, so they are *highly* sensitive. Make sure to never share your token or check it into any kind of version control. +:::warn +Your token is used to authorize API requests and carry your app's permissions, so they are *highly* sensitive. Make sure to never share your token or check it into any kind of version control. +::: Back in your project folder, rename the `.env.sample` file to `.env`. This is where we'll store all of your app's credentials. @@ -106,8 +109,9 @@ We'll need three values from your app's settings for your `.env` file: - Back on the **General Information** page, copy the value for **Public Key**, which is used to ensure HTTP requests are coming from Discord. In `.env`, replace `` with the value you copied. - On the **Bot** page under **Token**, click "Reset Token" to generate a new bot token. In `.env`, replace `` with your new token. -> warn -> You won't be able to view your token again unless you regenerate it, so make sure to keep it somewhere safe (like in a password manager). +:::warn +You won't be able to view your token again unless you regenerate it, so make sure to keep it somewhere safe (like in a password manager). +::: Now that you have the credentials you need, lets configure your bot user and installation settings. @@ -140,8 +144,9 @@ Now we'll select where your app can be installed in Discord, which is determined Click on **Installation** in the left sidebar, then under **Installation Contexts** make sure both "User Install" and "Guild Install" are selected. -> info -> Some apps may only want to support one installation context—for example, a moderation app may only support a server context. However, by default, we recommend supporting both installation contexts. For detailed information about supporting user-installed apps, you can read the [user-installable app tutorial](/docs/tutorials/developing-a-user-installable-app). +:::info +Some apps may only want to support one installation context—for example, a moderation app may only support a server context. However, by default, we recommend supporting both installation contexts. For detailed information about supporting user-installed apps, you can read the [user-installable app tutorial](/docs/tutorials/developing-a-user-installable-app). +::: ### Setting up an install link @@ -172,8 +177,9 @@ See a list of all [OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-sc ### Installing your app -> info -> When developing apps, you should build and test on your user account (for user-installable apps) and in a server that isn't actively used by others (for server-installable apps). If you don't have your own server already, you can [create one for free](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server-). +:::info +When developing apps, you should build and test on your user account (for user-installable apps) and in a server that isn't actively used by others (for server-installable apps). If you don't have your own server already, you can [create one for free](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server-). +::: Once you add scopes, copy the URL from the **Install Link** section from before. @@ -197,13 +203,15 @@ Follow the installation prompt to install your app to your user account. Once it With your app configured and installed to your test server and account, let's take a look at the code. -> info -> To make development a bit simpler, the app uses [discord-interactions](https://github.com/discord/discord-interactions-js), which provides types and helper functions. If you prefer to use other languages or libraries, check out the [Community Resources](/docs/developer-tools/community-resources) documentation. +:::info +To make development a bit simpler, the app uses [discord-interactions](https://github.com/discord/discord-interactions-js), which provides types and helper functions. If you prefer to use other languages or libraries, check out the [Community Resources](/docs/developer-tools/community-resources) documentation. +::: ### Installing slash commands -> info -> To install slash commands, the app is using [`node-fetch`](https://github.com/node-fetch/node-fetch). You can see the implementation for the installation in `utils.js` within the `DiscordRequest()` function. +:::info +To install slash commands, the app is using [`node-fetch`](https://github.com/node-fetch/node-fetch). You can see the implementation for the installation in `utils.js` within the `DiscordRequest()` function. +::: The project contains a `register` script you can use to install the commands in `ALL_COMMANDS`, which is defined at the bottom of `commands.js`. It installs the commands as global commands by calling the HTTP API's [`PUT /applications//commands`](/docs/interactions/application-commands#bulk-overwrite-global-application-commands) endpoint. @@ -242,8 +250,9 @@ npm run start There should be output indiciating your app is running on port `3000`. Behind the scenes, our app is ready to handle interactions from Discord, which includes verifying security request headers and responding to `PING` requests. We're skipping over a lot of the details in this tutorial, but details about preparing apps for interactions is in the [Interactions Overview](/docs/interactions/overview#preparing-for-interactions) documentation. -> info -> By default, the server will listen to requests sent to port 3000, but if you want to change the port, you can specify a `PORT` variable in your `.env` file. +:::info +By default, the server will listen to requests sent to port 3000, but if you want to change the port, you can specify a `PORT` variable in your `.env` file. +::: Next, we'll start our ngrok tunnel. If you don't have ngrok installed locally, you can install it by following the instructions on the [ngrok download page](https://ngrok.com/download). @@ -275,8 +284,9 @@ Go to your [app's settings](https://discord.com/developers/applications) and on Click **Save Changes** and ensure your endpoint is successfully verified. -> info -> If you have troubles verifying your endpoint, make sure both ngrok and your app are running on the same port, and that you've copied the ngrok URL correctly +:::info +If you have troubles verifying your endpoint, make sure both ngrok and your app are running on the same port, and that you've copied the ngrok URL correctly +::: The verification is handled automatically by the sample app in two ways: - It uses the `PUBLIC_KEY` and [discord-interactions package](https://github.com/discord/discord-interactions-js#usage) with a wrapper function (imported from `utils.js`) that makes it conform to [Express's `verify` interface](http://expressjs.com/en/5x/api.html#express.json). This is run on every incoming request to your app. @@ -304,8 +314,9 @@ if (name === 'test') { The code above is responding to the interaction with a message in the channel, DM, or Group DM it originated from. You can see all available response types, like responding with a modal, [in the documentation](/docs/interactions/receiving-and-responding#interaction-response-object-interaction-callback-type). -> info -> `InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE` is a constant [exported from `discord-interactions`](https://github.com/discord/discord-interactions-js/blob/main/src/index.ts#L33) +:::info +`InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE` is a constant [exported from `discord-interactions`](https://github.com/discord/discord-interactions-js/blob/main/src/index.ts#L33) +::: Go to your server and make sure your app's `/test` slash command works. When you trigger it, your app should send a message that contains “hello world” followed by a random emoji. @@ -323,8 +334,9 @@ The `/challenge` command, called `CHALLENGE_COMMAND` in `commands.js`, has an ar You can read more about command options and their structure [in the documentation](/docs/interactions/application-commands#application-command-object-application-command-option-structure). -> info -> While this guide won't touch much on the `game.js` file, feel free to poke around and change commands or the options in the commands. +:::info +While this guide won't touch much on the `game.js` file, feel free to poke around and change commands or the options in the commands. +::: @@ -369,16 +381,18 @@ if (name === 'challenge' && id) { } ``` -> info -> If you aren't sure where to paste the code, you can see the full code in `examples/app.js`. +:::info +If you aren't sure where to paste the code, you can see the full code in `examples/app.js`. +::: The above code is doing a few things: 1. Parses the request body to get the ID of the user who triggered the slash command (`userId`), and the option (object choice) they selected (`objectName`). If the interaction is run in a server (`context === 0`), the user ID will be nested in the `member` object. If it's in a DM or Group DM, it will be in the `user` object. 2. Adds a new game to the `activeGames` object using the interaction ID. The active game records the `userId` and `objectName`. 3. Sends a message back to the channel with a button with a `custom_id` of `accept_button_`. -> warn -> The sample code uses an object as in-memory storage, but for production apps you should use a database. +:::warn +The sample code uses an object as in-memory storage, but for production apps you should use a database. +::: When sending a message with [message components](/docs/interactions/message-components#what-is-a-component), the individual payloads are appended to a `components` array. Actionable components (like buttons) need to be inside of an [action row](/docs/interactions/message-components#action-rows), which you can see in the code sample. diff --git a/docs/reference.mdx b/docs/reference.mdx index fc1fae4404..3176ab3b5a 100644 --- a/docs/reference.mdx +++ b/docs/reference.mdx @@ -10,8 +10,9 @@ https://discord.com/api ## API Versioning -> danger -> Some API and Gateway versions are now non-functioning, and are labeled as discontinued in the table below for posterity. Trying to use these versions will fail and return 400 Bad Request. +:::danger +Some API and Gateway versions are now non-functioning, and are labeled as discontinued in the table below for posterity. Trying to use these versions will fail and return 400 Bad Request. +::: Discord exposes different versions of our API[.](https://c.tenor.com/BuZl66EegkgAAAAC/westworld-dolores.gif) You should specify which version to use by including it in the request path like `https://discord.com/api/v{version_number}`. Omitting the version number from the route will route requests to the current default version (marked below). You can find the change log for the newest API version [here](https://discord.com/developers/docs/change-log). @@ -232,8 +233,9 @@ User-Agent: DiscordBot ($url, $versionNumber) Clients may append more information and metadata to the _end_ of this string as they wish. -> warn -> Client requests that do not have a valid User Agent specified may be blocked and return a [Cloudflare error](https://support.cloudflare.com/hc/en-us/articles/360029779472-Troubleshooting-Cloudflare-1XXX-errors). +:::warn +Client requests that do not have a valid User Agent specified may be blocked and return a [Cloudflare error](https://support.cloudflare.com/hc/en-us/articles/360029779472-Troubleshooting-Cloudflare-1XXX-errors). +::: ### Content Type @@ -359,8 +361,9 @@ Discord uses ids and hashes to render images in the client. These hashes can be \*\*\*\* In the case of the Sticker endpoint, the sticker will be available as PNG if its [`format_type`](/docs/resources/sticker#sticker-object) is `PNG` or `APNG`, GIF if its `format_type` is `GIF`, and as [Lottie](https://airbnb.io/lottie/#/) if its `format_type` is `LOTTIE`. -> info -> Sticker GIFs do not use the CDN base url, and can be accessed at `https://media.discordapp.net/stickers/.gif`. +:::info +Sticker GIFs do not use the CDN base url, and can be accessed at `https://media.discordapp.net/stickers/.gif`. +::: ## Image Data @@ -396,8 +399,9 @@ https://cdn.discordapp.com/attachments/1012345678900020080/1234567891233211234/m ## Uploading Files -> info -> The file upload size limit applies to each file in a request. The default limit is `10 MiB` for all users, but may be higher for users depending on their [Nitro](https://support.discord.com/hc/en-us/articles/115000435108-What-are-Nitro-Nitro-Basic) status or by the server's [Boost Tier](https://support.discord.com/hc/en-us/articles/360028038352-Server-Boosting-FAQ-#h_419c3bd5-addd-4989-b7cf-c7957ef92583). The `attachment_size_limit` value provided [when working with interactions](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure) is calculated as the maximum of these values. +:::info +The file upload size limit applies to each file in a request. The default limit is `10 MiB` for all users, but may be higher for users depending on their [Nitro](https://support.discord.com/hc/en-us/articles/115000435108-What-are-Nitro-Nitro-Basic) status or by the server's [Boost Tier](https://support.discord.com/hc/en-us/articles/360028038352-Server-Boosting-FAQ-#h_419c3bd5-addd-4989-b7cf-c7957ef92583). The `attachment_size_limit` value provided [when working with interactions](/docs/interactions/receiving-and-responding#interaction-object-interaction-structure) is calculated as the maximum of these values. +::: Some endpoints support file attachments, indicated by the `files[n]` parameter. To add file(s), the standard `application/json` body must be replaced by a `multipart/form-data` body. The JSON message body can optionally be provided using the `payload_json` parameter. @@ -476,8 +480,9 @@ Content-Type: image/gif You can upload attachments when creating a message and use those attachments within your embed. To do this, you will want to upload files as part of your `multipart/form-data` body. Make sure that you're uploading files which contain a filename, as you will need to reference it in your payload. -> warn -> Only `.jpg`, `.jpeg`, `.png`, `.webp`, and `.gif` may be used at this time. Other file types are not supported. +:::warn +Only `.jpg`, `.jpeg`, `.png`, `.webp`, and `.gif` may be used at this time. Other file types are not supported. +::: Within an embed object, you can set an image to use an attachment as its URL with the attachment scheme syntax: `attachment://filename.png` diff --git a/docs/resources/application-role-connection-metadata.md b/docs/resources/application-role-connection-metadata.md index 6d5b356b67..4590502bdd 100644 --- a/docs/resources/application-role-connection-metadata.md +++ b/docs/resources/application-role-connection-metadata.md @@ -34,8 +34,9 @@ When a user connects their account using the bot's [`role_connections_verificati | BOOLEAN_EQUAL | 7 | the metadata value (`integer`) is equal to the guild's configured value (`integer`; `1`) | | BOOLEAN_NOT_EQUAL | 8 | the metadata value (`integer`) is not equal to the guild's configured value (`integer`; `1`) | -> info -> Each metadata type offers a comparison operation that allows guilds to configure role requirements based on metadata values stored by the bot. Bots specify a `metadata value` for each user and guilds specify the required `guild's configured value` within the guild role settings. +:::info +Each metadata type offers a comparison operation that allows guilds to configure role requirements based on metadata values stored by the bot. Bots specify a `metadata value` for each user and guilds specify the required `guild's configured value` within the guild role settings. +::: ## Get Application Role Connection Metadata Records % GET /applications/{application.id/docs/resources/application#application-object}/role-connections/metadata @@ -45,5 +46,6 @@ Returns a list of [application role connection metadata](/docs/resources/applica Updates and returns a list of [application role connection metadata](/docs/resources/application-role-connection-metadata#application-role-connection-metadata-object) objects for the given application. -> info -> An application can have a maximum of 5 metadata records. +:::info +An application can have a maximum of 5 metadata records. +::: diff --git a/docs/resources/application.md b/docs/resources/application.md index 1626cb5173..dc20d7a97a 100644 --- a/docs/resources/application.md +++ b/docs/resources/application.md @@ -182,8 +182,9 @@ By default, newly-created apps only support installation to guilds. You can update which installation contexts your app supports in your [app's settings](https://discord.com/developers/applications). On the **Installation** page under the **Installation Contexts** section, you can select the installation contexts your app supports. -> info -> If you update your app to support a new installation context, you will need to update your existing [commands](/docs/interactions/application-commands#contexts) if you want them to be supported in the new context. Details are in the [Application Command](/docs/interactions/application-commands#contexts) documentation. +:::info +If you update your app to support a new installation context, you will need to update your existing [commands](/docs/interactions/application-commands#contexts) if you want them to be supported in the new context. Details are in the [Application Command](/docs/interactions/application-commands#contexts) documentation. +::: ## Install Links @@ -193,8 +194,9 @@ Install links provide an easy way for users to install your app in Discord. If y There are three options when configuring an install link for your app: "Discord Provided Link", "Custom URL", and "None". If you don't configure an install link (by selecting "None"), the "Add App" button will not appear for your app, and your app will not be eligible for the App Directory. -> info -> Note that install links are distinct from OAuth2 flows like the [authorization code grant](/docs/topics/oauth2#authorization-code-grant), which may additionally be required if you need to request user-specific [scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) like `identify` or `role_connections.write`. +:::info +Note that install links are distinct from OAuth2 flows like the [authorization code grant](/docs/topics/oauth2#authorization-code-grant), which may additionally be required if you need to request user-specific [scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) like `identify` or `role_connections.write`. +::: #### Discord Provided Link @@ -208,8 +210,9 @@ https://discord.com/oauth2/authorize?client_id=1234567895647001626 Instead, these links will prompt the user for the scopes and bot user permissions configured in your Default Install Settings. -> info -> Discord Provided Links are limited to the `application.commands` and `bot` scopes +:::info +Discord Provided Links are limited to the `application.commands` and `bot` scopes +::: #### Custom URL @@ -231,8 +234,9 @@ Returns the [application](/docs/resources/application#application-object) object Edit properties of the app associated with the requesting bot user. Only properties that are passed will be updated. Returns the updated [application](/docs/resources/application#application-object) object on success. -> info -> All parameters to this endpoint are optional +:::info +All parameters to this endpoint are optional +::: ###### JSON Params diff --git a/docs/resources/audit-log.md b/docs/resources/audit-log.md index 4f8b3beb2c..8c5a925371 100644 --- a/docs/resources/audit-log.md +++ b/docs/resources/audit-log.md @@ -62,8 +62,9 @@ Apps can specify why an administrative action is being taken by passing an `X-Au | options? | [optional audit entry info](/docs/resources/audit-log#audit-log-entry-object-optional-audit-entry-info) | Additional info for certain event types | | reason? | string | Reason for the change (1-512 characters) | -> warn -> For `APPLICATION_COMMAND_PERMISSION_UPDATE` events, the `target_id` is the command ID or the app ID since the `changes` array represents the entire `permissions` property on the [guild permissions](/docs/interactions/application-commands#application-command-permissions-object-guild-application-command-permissions-structure) object. +:::warn +For `APPLICATION_COMMAND_PERMISSION_UPDATE` events, the `target_id` is the command ID or the app ID since the `changes` array represents the entire `permissions` property on the [guild permissions](/docs/interactions/application-commands#application-command-permissions-object-guild-application-command-permissions-structure) object. +::: ###### Audit Log Events @@ -73,8 +74,9 @@ The **Object Changed** column notes which object's values may be included in the If no object is noted, there won't be a `changes` array in the entry, though other fields like the `target_id` still exist and many have fields in the [`options` object](/docs/resources/audit-log#audit-log-entry-object-optional-audit-entry-info). -> info -> You should assume that your app may run into any field for the changed object, though none are guaranteed to be present. In most cases only a subset of the object's fields will be in the `changes` array. +:::info +You should assume that your app may run into any field for the changed object, though none are guaranteed to be present. In most cases only a subset of the object's fields will be in the `changes` array. +::: | Event | Value | Description | Object Changed | |---------------------------------------------|-------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| @@ -173,8 +175,9 @@ Many audit log events include a `changes` array in their [entry object](/docs/re Some events don't follow the same pattern as other audit log events. Details about these exceptions are explained in [the next section](/docs/resources/audit-log#audit-log-change-object-audit-log-change-exceptions). -> info -> If `new_value` is not present in the change object while `old_value` is, it indicates that the property has been reset or set to `null`. If `old_value` isn't included, it indicated that the property was previously `null`. +:::info +If `new_value` is not present in the change object while `old_value` is, it indicates that the property has been reset or set to `null`. If `old_value` isn't included, it indicated that the property was previously `null`. +::: | Field | Type | Description | diff --git a/docs/resources/auto-moderation.md b/docs/resources/auto-moderation.md index 0436d6c9e1..208365964a 100644 --- a/docs/resources/auto-moderation.md +++ b/docs/resources/auto-moderation.md @@ -202,25 +202,29 @@ Some [action types](/docs/resources/auto-moderation#auto-moderation-action-objec Get a list of all rules currently configured for the guild. Returns a list of [auto moderation rule](/docs/resources/auto-moderation#auto-moderation-rule-object) objects for the given guild. -> info -> This endpoint requires the `MANAGE_GUILD` [permission](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +:::info +This endpoint requires the `MANAGE_GUILD` [permission](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +::: ## Get Auto Moderation Rule % GET /guilds/{guild.id/docs/resources/guild#guild-object}/auto-moderation/rules/{auto_moderation_rule.id/docs/resources/auto-moderation#auto-moderation-rule-object} Get a single rule. Returns an [auto moderation rule](/docs/resources/auto-moderation#auto-moderation-rule-object) object. -> info -> This endpoint requires the `MANAGE_GUILD` [permission](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +:::info +This endpoint requires the `MANAGE_GUILD` [permission](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +::: ## Create Auto Moderation Rule % POST /guilds/{guild.id/docs/resources/guild#guild-object}/auto-moderation/rules Create a new rule. Returns an [auto moderation rule](/docs/resources/auto-moderation#auto-moderation-rule-object) on success. Fires an [Auto Moderation Rule Create](/docs/events/gateway-events#auto-moderation-rule-create) Gateway event. -> info -> This endpoint requires the `MANAGE_GUILD` [permission](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +:::info +This endpoint requires the `MANAGE_GUILD` [permission](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -237,22 +241,26 @@ Create a new rule. Returns an [auto moderation rule](/docs/resources/auto-modera \* Can be omitted based on `trigger_type`. See the `Associated Trigger Types` column in [trigger metadata](/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-metadata) to understand which `trigger_type` values require `trigger_metadata` to be set. -> info -> See [Trigger Types](/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-types) for limits on how many rules of each trigger type can be created per guild. +:::info +See [Trigger Types](/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-types) for limits on how many rules of each trigger type can be created per guild. +::: ## Modify Auto Moderation Rule % PATCH /guilds/{guild.id/docs/resources/guild#guild-object}/auto-moderation/rules/{auto_moderation_rule.id/docs/resources/auto-moderation#auto-moderation-rule-object} Modify an existing rule. Returns an [auto moderation rule](/docs/resources/auto-moderation#auto-moderation-rule-object) on success. Fires an [Auto Moderation Rule Update](/docs/events/gateway-events#auto-moderation-rule-update) Gateway event. -> info -> Requires `MANAGE_GUILD` [permissions](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +:::info +Requires `MANAGE_GUILD` [permissions](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +::: -> info -> All parameters for this endpoint are optional. +:::info +All parameters for this endpoint are optional. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -272,8 +280,10 @@ Modify an existing rule. Returns an [auto moderation rule](/docs/resources/auto- Delete a rule. Returns a `204` on success. Fires an [Auto Moderation Rule Delete](/docs/events/gateway-events#auto-moderation-rule-delete) Gateway event. -> info -> This endpoint requires the `MANAGE_GUILD` [permission](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +:::info +This endpoint requires the `MANAGE_GUILD` [permission](/docs/resources/auto-moderation#auto-moderation-permission-requirements). +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: diff --git a/docs/resources/channel.md b/docs/resources/channel.md index 9174426f82..d3f19df986 100644 --- a/docs/resources/channel.md +++ b/docs/resources/channel.md @@ -54,8 +54,9 @@ Represents a guild or DM channel within Discord. ###### Channel Types -> warn -> Type 10, 11 and 12 are only available in API v9 and above. +:::warn +Type 10, 11 and 12 are only available in API v9 and above. +::: | Type | ID | Description | |---------------------|----|------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -330,8 +331,9 @@ An object that represents a tag that is able to be applied to a thread in a `GUI ###### Forum Tag Structure -> info -> When updating a `GUILD_FORUM` or a `GUILD_MEDIA` channel, tag objects in `available_tags` only require the `name` field. +:::info +When updating a `GUILD_FORUM` or a `GUILD_MEDIA` channel, tag objects in `available_tags` only require the `name` field. +::: | Field | Type | Description | |------------|------------|----------------------------------------------------------------------------------------------------------------| @@ -351,11 +353,13 @@ Get a channel by ID. Returns a [channel](/docs/resources/channel#channel-object) Update a channel's settings. Returns a [channel](/docs/resources/channel#channel-object) on success, and a 400 BAD REQUEST on invalid parameters. -> info -> All parameters to this endpoint are optional +:::info +All parameters to this endpoint are optional +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params (Group DM) @@ -417,21 +421,25 @@ Otherwise, requires the `MANAGE_THREADS` permission. Fires a [Thread Update](/do Delete a channel, or close a private message. Requires the `MANAGE_CHANNELS` permission for the guild, or `MANAGE_THREADS` if the channel is a thread. Deleting a category does not delete its child channels; they will have their `parent_id` removed and a [Channel Update](/docs/events/gateway-events#channel-update) Gateway event will fire for each of them. Returns a [channel](/docs/resources/channel#channel-object) object on success. Fires a [Channel Delete](/docs/events/gateway-events#channel-delete) Gateway event (or [Thread Delete](/docs/events/gateway-events#thread-delete) if the channel was a thread). -> warn -> Deleting a guild channel cannot be undone. Use this with caution, as it is impossible to undo this action when performed on a guild channel. In contrast, when used with a private message, it is possible to undo the action by opening a private message with the recipient again. +:::warn +Deleting a guild channel cannot be undone. Use this with caution, as it is impossible to undo this action when performed on a guild channel. In contrast, when used with a private message, it is possible to undo the action by opening a private message with the recipient again. +::: -> info -> For Community guilds, the Rules or Guidelines channel and the Community Updates channel cannot be deleted. +:::info +For Community guilds, the Rules or Guidelines channel and the Community Updates channel cannot be deleted. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Edit Channel Permissions % PUT /channels/{channel.id/docs/resources/channel#channel-object}/permissions/{overwrite.id/docs/resources/channel#overwrite-object} Edit the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the `MANAGE_ROLES` permission. Only permissions your bot has in the guild or parent channel (if applicable) can be allowed/denied (unless your bot has a `MANAGE_ROLES` overwrite in the channel). Returns a 204 empty response on success. Fires a [Channel Update](/docs/events/gateway-events#channel-update) Gateway event. For more information about permissions, see [permissions](/docs/topics/permissions#permissions). -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -449,8 +457,9 @@ Returns a list of [invite](/docs/resources/invite#invite-object) objects (with [ Create a new [invite](/docs/resources/invite#invite-object) object for the channel. Only usable for guild channels. Requires the `CREATE_INSTANT_INVITE` permission. All JSON parameters for this route are optional, however the request body is not. If you are not sending any fields, you still have to send an empty JSON object (`{}`). Returns an [invite](/docs/resources/invite#invite-object) object. Fires an [Invite Create](/docs/events/gateway-events#invite-create) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -468,15 +477,17 @@ Create a new [invite](/docs/resources/invite#invite-object) object for the chann Delete a channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Channel Update](/docs/events/gateway-events#channel-update) Gateway event. For more information about permissions, see [permissions](/docs/topics/permissions#permissions) -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Follow Announcement Channel % POST /channels/{channel.id/docs/resources/channel#channel-object}/followers Follow an Announcement Channel to send messages to a target channel. Requires the `MANAGE_WEBHOOKS` permission in the target channel. Returns a [followed channel](/docs/resources/channel#followed-channel-object) object. Fires a [Webhooks Update](/docs/events/gateway-events#webhooks-update) Gateway event for the target channel. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -498,18 +509,21 @@ Returns all pinned messages in the channel as an array of [message](/docs/resour Pin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](/docs/events/gateway-events#channel-pins-update) Gateway event. -> warn -> The max pinned messages is 50. +:::warn +The max pinned messages is 50. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Unpin Message % DELETE /channels/{channel.id/docs/resources/channel#channel-object}/pins/{message.id/docs/resources/message#message-object} Unpin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](/docs/events/gateway-events#channel-pins-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Group DM Add Recipient % PUT /channels/{channel.id/docs/resources/channel#channel-object}/recipients/{user.id/docs/resources/user#user-object} @@ -532,8 +546,9 @@ Creates a new thread from an existing message. Returns a [channel](/docs/resourc When called on a `GUILD_TEXT` channel, creates a `PUBLIC_THREAD`. When called on a `GUILD_ANNOUNCEMENT` channel, creates a `ANNOUNCEMENT_THREAD`. Does not work on a [`GUILD_FORUM`](/docs/resources/channel#start-thread-in-forum-or-media-channel) or a `GUILD_MEDIA` channel. The id of the created thread will be the same as the id of the source message, and as such a message can only have a single thread created from it. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -547,8 +562,9 @@ When called on a `GUILD_TEXT` channel, creates a `PUBLIC_THREAD`. When called on Creates a new thread that is not connected to an existing message. Returns a [channel](/docs/resources/channel#channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](/docs/events/gateway-events#thread-create) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -575,11 +591,13 @@ Creates a new thread in a forum or a media channel, and sends a message within t - Files must be attached using a `multipart/form-data` body as described in [Uploading Files](/docs/reference#uploading-files). - Note that when sending a message, you must provide a value for at **least one of** `content`, `embeds`, `sticker_ids`, `components`, or `files[n]`. -> warn -> Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and using `allowed_mentions` to prevent unexpected mentions. +:::warn +Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and using `allowed_mentions` to prevent unexpected mentions. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON/Form Params @@ -596,8 +614,9 @@ Creates a new thread in a forum or a media channel, and sends a message within t ###### Forum and Media Thread Message Params Object -> info -> When sending a message, apps must provide a value for **at least one of** `content`, `embeds`, `sticker_ids`, `components`, or `files[n]`. +:::info +When sending a message, apps must provide a value for **at least one of** `content`, `embeds`, `sticker_ids`, `components`, or `files[n]`. +::: | Field | Type | Description | |-------------------|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -641,15 +660,17 @@ When `with_member` is set to `true`, the thread member object will include a `me ## List Thread Members % GET /channels/{channel.id/docs/resources/channel#channel-object}/thread-members -> warn -> Starting in API v11, this endpoint will always return paginated results. Paginated results can be enabled before API v11 by setting `with_member` to `true`. Read [the changelog](/docs/change-log#thread-member-details-and-pagination) for details. +:::warn +Starting in API v11, this endpoint will always return paginated results. Paginated results can be enabled before API v11 by setting `with_member` to `true`. Read [the changelog](/docs/change-log#thread-member-details-and-pagination) for details. +::: Returns array of [thread members](/docs/resources/channel#thread-member-object) objects that are members of the thread. When `with_member` is set to `true`, the results will be paginated and each thread member object will include a `member` field containing a [guild member](/docs/resources/guild#guild-member-object) object. -> warn -> This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](/docs/events/gateway#privileged-intents) is enabled for your application. +:::warn +This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](/docs/events/gateway#privileged-intents) is enabled for your application. +::: ###### Query String Params diff --git a/docs/resources/emoji.md b/docs/resources/emoji.md index c38fc345bf..c8823024d9 100644 --- a/docs/resources/emoji.md +++ b/docs/resources/emoji.md @@ -4,8 +4,9 @@ sidebar_label: Emoji # Emoji Resource -> warn -> Routes for controlling emojis do not follow the normal rate limit conventions. These routes are specifically limited on a per-guild basis to prevent abuse. This means that the quota returned by our APIs may be inaccurate, and you may encounter 429s. +:::warn +Routes for controlling emojis do not follow the normal rate limit conventions. These routes are specifically limited on a per-guild basis to prevent abuse. This means that the quota returned by our APIs may be inaccurate, and you may encounter 429s. +::: ### Emoji Object @@ -100,11 +101,13 @@ Returns an [emoji](/docs/resources/emoji#emoji-object) object for the given guil Create a new emoji for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [emoji](/docs/resources/emoji#emoji-object) object on success. Fires a [Guild Emojis Update](/docs/events/gateway-events#guild-emojis-update) Gateway event. -> warn -> Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a [JSON status code](/docs/topics/opcodes-and-status-codes#json). +:::warn +Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a [JSON status code](/docs/topics/opcodes-and-status-codes#json). +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -118,11 +121,13 @@ Create a new emoji for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permis Modify the given emoji. For emojis created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other emojis, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [emoji](/docs/resources/emoji#emoji-object) object on success. Fires a [Guild Emojis Update](/docs/events/gateway-events#guild-emojis-update) Gateway event. -> info -> All parameters to this endpoint are optional. +:::info +All parameters to this endpoint are optional. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -135,8 +140,9 @@ Modify the given emoji. For emojis created by the current user, requires either Delete the given emoji. For emojis created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other emojis, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Emojis Update](/docs/events/gateway-events#guild-emojis-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## List Application Emojis % GET /applications/{application.id/docs/resources/application#application-object}/emojis @@ -172,8 +178,9 @@ Returns an [emoji](/docs/resources/emoji#emoji-object) object for the given appl Create a new emoji for the application. Returns the new [emoji](/docs/resources/emoji#emoji-object) object on success. -> warn -> Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a [JSON status code](/docs/topics/opcodes-and-status-codes#json). +:::warn +Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a [JSON status code](/docs/topics/opcodes-and-status-codes#json). +::: ###### JSON Params diff --git a/docs/resources/guild-scheduled-event.mdx b/docs/resources/guild-scheduled-event.mdx index 82c6a5870c..6e41b35a4d 100644 --- a/docs/resources/guild-scheduled-event.mdx +++ b/docs/resources/guild-scheduled-event.mdx @@ -104,8 +104,9 @@ SCHEDULED --> CANCELED ### Guild Scheduled Event Recurrence Rule Object Discord's recurrence rule is a subset of the behaviors [defined in the iCalendar RFC](https://datatracker.ietf.org/doc/html/rfc5545) and implemented by [python's dateutil rrule](https://dateutil.readthedocs.io/en/stable/rrule.html) -> warn -> There are currently many limitations to this system. Please see "System limitations" below +:::warn +There are currently many limitations to this system. Please see "System limitations" below +::: ###### Guild Scheduled Event Recurrence Rule Structure @@ -273,11 +274,13 @@ Returns a list of [guild scheduled event](/docs/resources/guild-scheduled-event# Create a guild scheduled event in the guild. Returns a [guild scheduled event](/docs/resources/guild-scheduled-event#guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Create](/docs/events/gateway-events#guild-scheduled-event-create) Gateway event. -> info -> A guild can have a maximum of 100 events with `SCHEDULED` or `ACTIVE` status at any time. +:::info +A guild can have a maximum of 100 events with `SCHEDULED` or `ACTIVE` status at any time. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -313,17 +316,21 @@ Get a guild scheduled event. Returns a [guild scheduled event](/docs/resources/g Modify a guild scheduled event. Returns the modified [guild scheduled event](/docs/resources/guild-scheduled-event#guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Update](/docs/events/gateway-events#guild-scheduled-event-update) Gateway event. -> info -> To start or end an event, use this endpoint to modify the event's [status](/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-status) field. +:::info +To start or end an event, use this endpoint to modify the event's [status](/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-status) field. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: -> info -> This endpoint silently discards `entity_metadata` for non-`EXTERNAL` events. +:::info +This endpoint silently discards `entity_metadata` for non-`EXTERNAL` events. +::: -> info -> All parameters to this endpoint are optional +:::info +All parameters to this endpoint are optional +::: ###### JSON Params @@ -396,9 +403,9 @@ Any event with `'status': SCHEDULED` after a certain time interval (on the order NOTE: `entity_type` is expressed by name rather than value for readability -> info -> A user must be a member of the guild in order to access events for that guild unless the guild is lurkable. If a guild is lurkable, -> events in that guild may be visible to lurkers depending on the event type and the permissions of any channels associated with the event. +:::info +A user must be a member of the guild in order to access events for that guild unless the guild is lurkable. If a guild is lurkable, events in that guild may be visible to lurkers depending on the event type and the permissions of any channels associated with the event. +::: ### Permissions for events with entity_type: STAGE_INSTANCE diff --git a/docs/resources/guild-template.md b/docs/resources/guild-template.md index 0f867e7fd5..59b0faefdb 100644 --- a/docs/resources/guild-template.md +++ b/docs/resources/guild-template.md @@ -107,8 +107,9 @@ Returns a [guild template](/docs/resources/guild-template#guild-template-object) Create a new guild based on a template. Returns a [guild](/docs/resources/guild#guild-object) object on success. Fires a [Guild Create](/docs/events/gateway-events#guild-create) Gateway event. -> warn -> This endpoint can be used only by bots in less than 10 guilds. +:::warn +This endpoint can be used only by bots in less than 10 guilds. +::: ###### JSON Params diff --git a/docs/resources/guild.md b/docs/resources/guild.md index fc84f33d22..28604339f0 100644 --- a/docs/resources/guild.md +++ b/docs/resources/guild.md @@ -10,8 +10,9 @@ Guilds in Discord represent an isolated collection of users and channels, and ar ###### Guild Structure -> info -> Fields specific to the `GUILD_CREATE` event are listed in the [Gateway Events documentation](/docs/events/gateway-events#guild-create). +:::info +Fields specific to the `GUILD_CREATE` event are listed in the [Gateway Events documentation](/docs/events/gateway-events#guild-create). +::: | Field | Type | Description | |--------------------------------|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -309,8 +310,9 @@ A partial [guild](/docs/resources/guild#guild-object) object. Represents an Offl | members | array of partial [user](/docs/resources/user#user-object) objects | special widget user objects that includes users presence (Limit 100) | | presence_count | integer | number of online members in this guild | -> warn -> The fields `id`, `discriminator` and `avatar` are anonymized to prevent abuse. +:::warn +The fields `id`, `discriminator` and `avatar` are anonymized to prevent abuse. +::: ###### Example Guild Widget @@ -366,11 +368,13 @@ A partial [guild](/docs/resources/guild#guild-object) object. Represents an Offl | communication_disabled_until? | ?ISO8601 timestamp | when the user's [timeout](https://support.discord.com/hc/en-us/articles/4413305239191-Time-Out-FAQ) will expire and the user will be able to communicate in the guild again, null or a time in the past if the user is not timed out | | avatar_decoration_data? | ?[avatar decoration data](/docs/resources/user#avatar-decoration-data-object) object | data for the member's guild avatar decoration | -> info -> The field `user` won't be included in the member object attached to `MESSAGE_CREATE` and `MESSAGE_UPDATE` gateway events. +:::info +The field `user` won't be included in the member object attached to `MESSAGE_CREATE` and `MESSAGE_UPDATE` gateway events. +::: -> info -> In `GUILD_` events, `pending` will always be included as true or false. In non `GUILD_` events which can only be triggered by non-`pending` users, `pending` will not be included. +:::info +In `GUILD_` events, `pending` will always be included as true or false. In non `GUILD_` events which can only be triggered by non-`pending` users, `pending` will not be included. +::: ###### Example Guild Member @@ -401,8 +405,9 @@ A partial [guild](/docs/resources/guild#guild-object) object. Represents an Offl | AUTOMOD_QUARANTINED_USERNAME | `1 << 7` | Member's username, display name, or nickname is blocked by AutoMod | false | | DM_SETTINGS_UPSELL_ACKNOWLEDGED | `1 << 9` | Member has dismissed the DM settings upsell | false | -> info -> BYPASSES_VERIFICATION allows a member who does not meet verification requirements to participate in a server. +:::info +BYPASSES_VERIFICATION allows a member who does not meet verification requirements to participate in a server. +::: ### Integration Object @@ -428,8 +433,9 @@ A partial [guild](/docs/resources/guild#guild-object) object. Represents an Offl | scopes? | array of [OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) | the scopes the application has been authorized for | \* These fields are not provided for discord bot integrations. -> warn -> Some older integrations may not have an attached user. +:::warn +Some older integrations may not have an attached user. +::: ###### Integration Expire Behaviors @@ -581,8 +587,9 @@ Represents the [onboarding](https://support.discord.com/hc/en-us/articles/110749 | title | string | Title of the option | | description | ?string | Description of the option | -> warn -> When creating or updating a prompt option, the `emoji_id`, `emoji_name`, and `emoji_animated` fields must be used instead of the emoji object. +:::warn +When creating or updating a prompt option, the `emoji_id`, `emoji_name`, and `emoji_animated` fields must be used instead of the emoji object. +::: ###### Onboarding Mode @@ -662,8 +669,9 @@ Defines the criteria used to satisfy Onboarding constraints that are required fo In guilds with [Membership Screening](https://support.discord.com/hc/en-us/articles/1500000466882) enabled, when a member joins, [Guild Member Add](/docs/events/gateway-events#guild-member-add) will be emitted but they will initially be restricted from doing any actions in the guild, and `pending` will be true in the [member object](/docs/resources/guild#guild-member-object). When the member completes the screening, [Guild Member Update](/docs/events/gateway-events#guild-member-update) will be emitted and `pending` will be false. -> warn -> We are making significant changes to the Membership Screening API specifically related to getting and editing the Membership Screening object. Long story short is that it can be improved. As such, we have removed those documentation. There will **not be** any changes to how pending members work, as outlined above. That behavior will stay the same. +:::warn +We are making significant changes to the Membership Screening API specifically related to getting and editing the Membership Screening object. Long story short is that it can be improved. As such, we have removed those documentation. There will **not be** any changes to how pending members work, as outlined above. That behavior will stay the same. +::: ### Incidents Data Object @@ -689,8 +697,9 @@ In guilds with [Membership Screening](https://support.discord.com/hc/en-us/artic Create a new guild. Returns a [guild](/docs/resources/guild#guild-object) object on success. Fires a [Guild Create](/docs/events/gateway-events#guild-create) Gateway event. -> warn -> This endpoint can be used only by bots in less than 10 guilds. +:::warn +This endpoint can be used only by bots in less than 10 guilds. +::: ###### JSON Params @@ -709,20 +718,25 @@ Create a new guild. Returns a [guild](/docs/resources/guild#guild-object) object | system_channel_id? | snowflake | the id of the channel where guild notices such as welcome messages and boost events are posted | | system_channel_flags? | integer | [system channel flags](/docs/resources/guild#guild-object-system-channel-flags) | -> warn -> When using the `roles` parameter, the first member of the array is used to change properties of the guild's `@everyone` role. If you are trying to bootstrap a guild with additional roles, keep this in mind. +:::warn +When using the `roles` parameter, the first member of the array is used to change properties of the guild's `@everyone` role. If you are trying to bootstrap a guild with additional roles, keep this in mind. +::: -> info -> When using the `roles` parameter, the required `id` field within each role object is an integer placeholder, and will be replaced by the API upon consumption. Its purpose is to allow you to [overwrite](/docs/resources/channel#overwrite-object) a role's permissions in a channel when also passing in channels with the channels array. +:::info +When using the `roles` parameter, the required `id` field within each role object is an integer placeholder, and will be replaced by the API upon consumption. Its purpose is to allow you to [overwrite](/docs/resources/channel#overwrite-object) a role's permissions in a channel when also passing in channels with the channels array. +::: -> warn -> When using the `channels` parameter, the `position` field is ignored, and none of the default channels are created. +:::warn +When using the `channels` parameter, the `position` field is ignored, and none of the default channels are created. +::: -> info -> When using the `channels` parameter, the `id` field within each channel object may be set to an integer placeholder, and will be replaced by the API upon consumption. Its purpose is to allow you to create `GUILD_CATEGORY` channels by setting the `parent_id` field on any children to the category's `id` field. Category channels must be listed before any children. +:::info +When using the `channels` parameter, the `id` field within each channel object may be set to an integer placeholder, and will be replaced by the API upon consumption. Its purpose is to allow you to create `GUILD_CATEGORY` channels by setting the `parent_id` field on any children to the category's `id` field. Category channels must be listed before any children. +::: -> warn -> The `region` field is deprecated and is replaced by [channel.rtc_region](/docs/resources/channel#channel-object-channel-structure). +:::warn +The `region` field is deprecated and is replaced by [channel.rtc_region](/docs/resources/channel#channel-object-channel-structure). +::: ###### Example Partial Channel Object @@ -839,14 +853,17 @@ If the user is not in the guild, then the guild must be [discoverable](/docs/res Modify a guild's settings. Requires the `MANAGE_GUILD` permission. Returns the updated [guild](/docs/resources/guild#guild-object) object on success. Fires a [Guild Update](/docs/events/gateway-events#guild-update) Gateway event. -> info -> All parameters to this endpoint are optional +:::info +All parameters to this endpoint are optional +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: -> warn -> Attempting to add or remove the `COMMUNITY` [guild feature](/docs/resources/guild#guild-object-guild-features) requires the `ADMINISTRATOR` permission. +:::warn +Attempting to add or remove the `COMMUNITY` [guild feature](/docs/resources/guild#guild-object-guild-features) requires the `ADMINISTRATOR` permission. +::: ###### JSON Params @@ -886,11 +903,13 @@ Returns a list of guild [channel](/docs/resources/channel#channel-object) object Create a new [channel](/docs/resources/channel#channel-object) object for the guild. Requires the `MANAGE_CHANNELS` permission. If setting permission overwrites, only permissions your bot has in the guild can be allowed/denied. Setting `MANAGE_ROLES` permission in channels is only possible for guild administrators. Returns the new [channel](/docs/resources/channel#channel-object) object on success. Fires a [Channel Create](/docs/events/gateway-events#channel-create) Gateway event. -> info -> All parameters to this endpoint are optional and nullable excluding `name` +:::info +All parameters to this endpoint are optional and nullable excluding `name` +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -923,8 +942,9 @@ Create a new [channel](/docs/resources/channel#channel-object) object for the gu Modify the positions of a set of [channel](/docs/resources/channel#channel-object) objects for the guild. Requires `MANAGE_CHANNELS` permission. Returns a 204 empty response on success. Fires multiple [Channel Update](/docs/events/gateway-events#channel-update) Gateway events. -> info -> Only channels to be modified are required. +:::info +Only channels to be modified are required. +::: This endpoint takes a JSON array of parameters in the following format: @@ -956,11 +976,13 @@ Returns a [guild member](/docs/resources/guild#guild-member-object) object for t Returns a list of [guild member](/docs/resources/guild#guild-member-object) objects that are members of the guild. -> warn -> This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](/docs/events/gateway#privileged-intents) is enabled for your application. +:::warn +This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](/docs/events/gateway#privileged-intents) is enabled for your application. +::: -> info -> All parameters to this endpoint are optional +:::info +All parameters to this endpoint are optional +::: ###### Query String Params @@ -973,8 +995,9 @@ Returns a list of [guild member](/docs/resources/guild#guild-member-object) obje Returns a list of [guild member](/docs/resources/guild#guild-member-object) objects whose username or nickname starts with a provided string. -> info -> All parameters to this endpoint except for `query` are optional +:::info +All parameters to this endpoint except for `query` are optional +::: ###### Query String Params @@ -989,11 +1012,13 @@ Adds a user to the guild, provided you have a valid oauth2 access token for the For guilds with [Membership Screening](/docs/resources/guild#membership-screening-object) enabled, this endpoint will default to adding new members as `pending` in the [guild member object](/docs/resources/guild#guild-member-object). Members that are `pending` will have to complete membership screening before they become full members that can talk. -> info -> All parameters to this endpoint except for `access_token` are optional. +:::info +All parameters to this endpoint except for `access_token` are optional. +::: -> info -> The Authorization header must be a Bot token (belonging to the same application used for authorization), and the bot must be a member of the guild with `CREATE_INSTANT_INVITE` permission. +:::info +The Authorization header must be a Bot token (belonging to the same application used for authorization), and the bot must be a member of the guild with `CREATE_INSTANT_INVITE` permission. +::: ###### JSON Params @@ -1010,11 +1035,13 @@ For guilds with [Membership Screening](/docs/resources/guild#membership-screenin Modify attributes of a [guild member](/docs/resources/guild#guild-member-object). Returns a 200 OK with the [guild member](/docs/resources/guild#guild-member-object) as the body. Fires a [Guild Member Update](/docs/events/gateway-events#guild-member-update) Gateway event. If the `channel_id` is set to null, this will force the target user to be disconnected from voice. -> info -> All parameters to this endpoint are optional and nullable. When moving members to channels, the API user _must_ have permissions to both connect to the channel and have the `MOVE_MEMBERS` permission. +:::info +All parameters to this endpoint are optional and nullable. When moving members to channels, the API user _must_ have permissions to both connect to the channel and have the `MOVE_MEMBERS` permission. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1032,8 +1059,9 @@ Modify attributes of a [guild member](/docs/resources/guild#guild-member-object) Modifies the current member in a guild. Returns a 200 with the updated member object on success. Fires a [Guild Member Update](/docs/events/gateway-events#guild-member-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1043,13 +1071,15 @@ Modifies the current member in a guild. Returns a 200 with the updated member ob ## Modify Current User Nick % PATCH /guilds/{guild.id/docs/resources/guild#guild-object}/members/@me/nick -> danger -> Deprecated in favor of [Modify Current Member](/docs/resources/guild#modify-current-member). +:::danger +Deprecated in favor of [Modify Current Member](/docs/resources/guild#modify-current-member). +::: Modifies the nickname of the current user in a guild. Returns a 200 with the nickname on success. Fires a [Guild Member Update](/docs/events/gateway-events#guild-member-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1061,22 +1091,25 @@ Modifies the nickname of the current user in a guild. Returns a 200 with the nic Adds a role to a [guild member](/docs/resources/guild#guild-member-object). Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Guild Member Update](/docs/events/gateway-events#guild-member-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Remove Guild Member Role % DELETE /guilds/{guild.id/docs/resources/guild#guild-object}/members/{user.id/docs/resources/user#user-object}/roles/{role.id/docs/topics/permissions#role-object} Removes a role from a [guild member](/docs/resources/guild#guild-member-object). Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Guild Member Update](/docs/events/gateway-events#guild-member-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Remove Guild Member % DELETE /guilds/{guild.id/docs/resources/guild#guild-object}/members/{user.id/docs/resources/user#user-object} Remove a member from a guild. Requires `KICK_MEMBERS` permission. Returns a 204 empty response on success. Fires a [Guild Member Remove](/docs/events/gateway-events#guild-member-remove) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Get Guild Bans % GET /guilds/{guild.id/docs/resources/guild#guild-object}/bans @@ -1100,8 +1133,9 @@ Returns a [ban](/docs/resources/guild#ban-object) object for the given user or a Create a guild ban, and optionally delete previous messages sent by the banned user. Requires the `BAN_MEMBERS` permission. Returns a 204 empty response on success. Fires a [Guild Ban Add](/docs/events/gateway-events#guild-ban-add) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1114,15 +1148,17 @@ Create a guild ban, and optionally delete previous messages sent by the banned u Remove the ban for a user. Requires the `BAN_MEMBERS` permissions. Returns a 204 empty response on success. Fires a [Guild Ban Remove](/docs/events/gateway-events#guild-ban-remove) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Bulk Guild Ban % POST /guilds/{guild.id/docs/resources/guild#guild-object}/bulk-ban Ban up to 200 users from a guild, and optionally delete previous messages sent by the banned users. Requires both the `BAN_MEMBERS` and `MANAGE_GUILD` permissions. Returns a 200 response on success, including the fields `banned_users` with the IDs of the banned users and `failed_users` with IDs that could not be banned or were already banned. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1140,8 +1176,9 @@ On success, this endpoint returns a 200 success response with the following body | banned_users | array of snowflakes | list of user ids, that were successfully banned | | failed_users | array of snowflakes | list of user ids, that were not banned | -> info -> If none of the users could be banned, an error response code `500000: Failed to ban users` is returned instead. +:::info +If none of the users could be banned, an error response code `500000: Failed to ban users` is returned instead. +::: ## Get Guild Roles % GET /guilds/{guild.id/docs/resources/guild#guild-object}/roles @@ -1155,8 +1192,9 @@ Returns a [role](/docs/topics/permissions#role-object) object for the specified Create a new [role](/docs/topics/permissions#role-object) for the guild. Requires the `MANAGE_ROLES` permission. Returns the new [role](/docs/topics/permissions#role-object) object on success. Fires a [Guild Role Create](/docs/events/gateway-events#guild-role-create) Gateway event. All JSON params are optional. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1174,8 +1212,9 @@ Create a new [role](/docs/topics/permissions#role-object) for the guild. Require Modify the positions of a set of [role](/docs/topics/permissions#role-object) objects for the guild. Requires the `MANAGE_ROLES` permission. Returns a list of all of the guild's [role](/docs/topics/permissions#role-object) objects on success. Fires multiple [Guild Role Update](/docs/events/gateway-events#guild-role-update) Gateway events. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: This endpoint takes a JSON array of parameters in the following format: @@ -1190,11 +1229,13 @@ This endpoint takes a JSON array of parameters in the following format: Modify a guild role. Requires the `MANAGE_ROLES` permission. Returns the updated [role](/docs/topics/permissions#role-object) on success. Fires a [Guild Role Update](/docs/events/gateway-events#guild-role-update) Gateway event. -> info -> All parameters to this endpoint are optional and nullable. +:::info +All parameters to this endpoint are optional and nullable. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1212,8 +1253,9 @@ Modify a guild role. Requires the `MANAGE_ROLES` permission. Returns the updated Modify a guild's MFA level. Requires guild ownership. Returns the updated [level](/docs/resources/guild#guild-object-mfa-level) on success. Fires a [Guild Update](/docs/events/gateway-events#guild-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1225,8 +1267,9 @@ Modify a guild's MFA level. Requires guild ownership. Returns the updated [level Delete a guild role. Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Guild Role Delete](/docs/events/gateway-events#guild-role-delete) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Get Guild Prune Count % GET /guilds/{guild.id/docs/resources/guild#guild-object}/prune @@ -1247,8 +1290,9 @@ Begin a prune operation. Requires the `MANAGE_GUILD` and `KICK_MEMBERS` permissi By default, prune will not remove users with roles. You can optionally include specific roles in your prune by providing the `include_roles` parameter. Any inactive user that has a subset of the provided role(s) will be included in the prune and users with additional roles will not. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1271,15 +1315,17 @@ Returns a list of [invite](/docs/resources/invite#invite-object) objects (with [ Returns a list of [integration](/docs/resources/guild#integration-object) objects for the guild. Requires the `MANAGE_GUILD` permission. -> info -> This endpoint returns a maximum of 50 integrations. If a guild has more integrations, they cannot be accessed. +:::info +This endpoint returns a maximum of 50 integrations. If a guild has more integrations, they cannot be accessed. +::: ## Delete Guild Integration % DELETE /guilds/{guild.id/docs/resources/guild#guild-object}/integrations/{integration.id/docs/resources/guild#integration-object} Delete the attached [integration](/docs/resources/guild#integration-object) object for the guild. Deletes any associated webhooks and kicks the associated bot if there is one. Requires the `MANAGE_GUILD` permission. Returns a 204 empty response on success. Fires [Guild Integrations Update](/docs/events/gateway-events#guild-integrations-update) and [Integration Delete](/docs/events/gateway-events#integration-delete) Gateway events. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Get Guild Widget Settings % GET /guilds/{guild.id/docs/resources/guild#guild-object}/widget @@ -1289,8 +1335,9 @@ Returns a [guild widget settings](/docs/resources/guild#guild-widget-settings-ob Modify a [guild widget settings](/docs/resources/guild#guild-widget-settings-object) object for the guild. All attributes may be passed in with JSON and modified. Requires the `MANAGE_GUILD` permission. Returns the updated [guild widget settings](/docs/resources/guild#guild-widget-settings-object) object. Fires a [Guild Update](/docs/events/gateway-events#guild-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Get Guild Widget % GET /guilds/{guild.id/docs/resources/guild#guild-object}/widget.json @@ -1300,8 +1347,9 @@ Returns the [widget](/docs/resources/guild#guild-widget-object) for the guild. F Returns a partial [invite](/docs/resources/invite#invite-object) object for guilds with that feature enabled. Requires the `MANAGE_GUILD` permission. `code` will be null if a vanity url for the guild is not set. -> info -> This endpoint is required to get the usage count of the vanity invite, but the invite code can be accessed as `vanity_url_code` in the [guild object](/docs/resources/guild#guild-object) without having the `MANAGE_GUILD` permission. +:::info +This endpoint is required to get the usage count of the vanity invite, but the invite code can be accessed as `vanity_url_code` in the [guild object](/docs/resources/guild#guild-object) without having the `MANAGE_GUILD` permission. +::: ###### Example Partial Invite Object @@ -1316,8 +1364,9 @@ Returns a partial [invite](/docs/resources/invite#invite-object) object for guil Returns a PNG image widget for the guild. Requires no permissions or authentication. -> info -> All parameters to this endpoint are optional. +:::info +All parameters to this endpoint are optional. +::: ###### Query String Params @@ -1343,11 +1392,13 @@ Returns the [Welcome Screen](/docs/resources/guild#welcome-screen-object) object Modify the guild's [Welcome Screen](/docs/resources/guild#welcome-screen-object). Requires the `MANAGE_GUILD` permission. Returns the updated [Welcome Screen](/docs/resources/guild#welcome-screen-object) object. May fire a [Guild Update](/docs/events/gateway-events#guild-update) Gateway event. -> info -> All parameters to this endpoint are optional and nullable +:::info +All parameters to this endpoint are optional and nullable +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1365,11 +1416,13 @@ Returns the [Onboarding](/docs/resources/guild#guild-onboarding-object) object f Modifies the onboarding configuration of the guild. Returns a 200 with the [Onboarding](/docs/resources/guild#guild-onboarding-object) object for the guild. Requires the `MANAGE_GUILD` and `MANAGE_ROLES` permissions. -> info -> Onboarding enforces constraints when enabled. These constraints are that there must be at least 7 Default Channels and at least 5 of them must allow sending messages to the @everyone role. The `mode` field modifies what is considered when enforcing these constraints. +:::info +Onboarding enforces constraints when enabled. These constraints are that there must be at least 7 Default Channels and at least 5 of them must allow sending messages to the @everyone role. The `mode` field modifies what is considered when enforcing these constraints. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -1386,8 +1439,9 @@ Modifies the incident actions of the guild. Returns a 200 with the [Incidents Da ###### JSON Params -> info -> Both `invites_disabled_until` and `dms_disabled_until` can be enabled for a maximal timespan of 24 hours in the future. +:::info +Both `invites_disabled_until` and `dms_disabled_until` can be enabled for a maximal timespan of 24 hours in the future. +::: | Field | Type | Description | |-------------------------|-----------------------|--------------------------------------------| diff --git a/docs/resources/invite.md b/docs/resources/invite.md index 02ffbd7400..4b3a365b89 100644 --- a/docs/resources/invite.md +++ b/docs/resources/invite.md @@ -111,8 +111,9 @@ Extra information about an invite, will extend the [invite](/docs/resources/invi ### Invite Stage Instance Object -> warn -> This is deprecated. +:::warn +This is deprecated. +::: ###### Invite Stage Instance Structure @@ -160,5 +161,6 @@ Returns an [invite](/docs/resources/invite#invite-object) object for the given c Delete an invite. Requires the `MANAGE_CHANNELS` permission on the channel this invite belongs to, or `MANAGE_GUILD` to remove any invite across the guild. Returns an [invite](/docs/resources/invite#invite-object) object on success. Fires an [Invite Delete](/docs/events/gateway-events#invite-delete) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: diff --git a/docs/resources/lobby.md b/docs/resources/lobby.md index 54bdf41a89..97bb7c6e6a 100644 --- a/docs/resources/lobby.md +++ b/docs/resources/lobby.md @@ -62,8 +62,9 @@ Creates a new lobby, adding any of the specified members to it, if provided. Returns a [lobby](/docs/resources/lobby#lobby-object) object. -> info -> [Discord Social SDK](/docs/discord-social-sdk/overview) clients will not be able to join or leave a lobby created using this API, such as [`Client::CreateOrJoinLobby`]. See [Managing Lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies) for more information. +:::info +[Discord Social SDK](/docs/discord-social-sdk/overview) clients will not be able to join or leave a lobby created using this API, such as [`Client::CreateOrJoinLobby`]. See [Managing Lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies) for more information. +::: ### JSON Params diff --git a/docs/resources/message.md b/docs/resources/message.md index d2472deec6..5aaba09743 100644 --- a/docs/resources/message.md +++ b/docs/resources/message.md @@ -10,11 +10,13 @@ Represents a message sent in a channel within Discord. ###### Message Structure -> info -> Fields specific to the `MESSAGE_CREATE` and `MESSAGE_UPDATE` events are listed in the [Gateway documentation](/docs/events/gateway-events#message-create). +:::info +Fields specific to the `MESSAGE_CREATE` and `MESSAGE_UPDATE` events are listed in the [Gateway documentation](/docs/events/gateway-events#message-create). +::: -> warn -> An app will receive empty values in the `content`, `embeds`, `attachments`, and `components` fields while `poll` will be omitted if they have not configured (or been approved for) the [`MESSAGE_CONTENT` privileged intent (`1 << 15`)](/docs/events/gateway#message-content-intent). +:::warn +An app will receive empty values in the `content`, `embeds`, `attachments`, and `components` fields while `poll` will be omitted if they have not configured (or been approved for) the [`MESSAGE_CONTENT` privileged intent (`1 << 15`)](/docs/events/gateway#message-content-intent). +::: | Field | Type | Description | |---------------------------|------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -67,8 +69,9 @@ Represents a message sent in a channel within Discord. ###### Message Types -> warn -> Type `19` and `20` are only available in API v8 and above. In v6, they are represented as type `0`. Additionally, type `21` is only available in API v9 and above. +:::warn +Type `19` and `20` are only available in API v8 and above. In v6, they are represented as type `0`. Additionally, type `21` is only available in API v9 and above. +::: | Type | Value | Deletable | |----------------------------------------------|-------|-----------| @@ -419,8 +422,9 @@ The encoding, and the waveform details, are an implementation detail and may cha \* The current subset of message fields consists of: `type`, `content`, `embeds`, `attachments`, `timestamp`, `edited_timestamp`, `flags`, `mentions`, `mention_roles`, `stickers`, `sticker_items`, and `components`. -> info -> While message snapshots are able to support nested snapshots, we currently limit the depth of nesting to 1. +:::info +While message snapshots are able to support nested snapshots, we currently limit the depth of nesting to 1. +::: ### Reaction Object @@ -578,8 +582,9 @@ Certain embed types are used to power special UIs. These embeds use [fields](/do ###### Attachment Structure -> info -> For the `attachments` array in Message Create/Edit requests, only the `id` is required. +:::info +For the `attachments` array in Message Create/Edit requests, only the `id` is required. +::: | Field | Type | Description | |----------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------| @@ -737,8 +742,9 @@ If operating on a guild channel, this endpoint requires the current user to have If the current user is missing the `READ_MESSAGE_HISTORY` permission in the channel, then no messages will be returned. -> info -> The `before`, `after`, and `around` parameters are mutually exclusive, only one may be passed at a time. +:::info +The `before`, `after`, and `around` parameters are mutually exclusive, only one may be passed at a time. +::: ###### Query String Params @@ -757,8 +763,9 @@ If operating on a guild channel, this endpoint requires the current user to have ## Create Message % POST /channels/{channel.id/docs/resources/channel#channel-object}/messages -> warn -> Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and using `allowed_mentions` to prevent unexpected mentions. +:::warn +Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and using `allowed_mentions` to prevent unexpected mentions. +::: Post a message to a guild text or DM channel. Returns a [message](/docs/resources/message#message-object) object. Fires a [Message Create](/docs/events/gateway-events#message-create) Gateway event. See [message formatting](/docs/reference#message-formatting) for more information on how to properly format messages. @@ -778,8 +785,9 @@ Files must be attached using a `multipart/form-data` body as described in [Uploa ###### JSON/Form Params -> info -> When creating a message, apps must provide a value for **at least one of** `content`, `embeds`, `sticker_ids`, `components`, `files[n]`, or `poll`. +:::info +When creating a message, apps must provide a value for **at least one of** `content`, `embeds`, `sticker_ids`, `components`, `files[n]`, or `poll`. +::: | Field | Type | Description | |--------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -876,11 +884,13 @@ Returns a [message](/docs/resources/message#message-object) object. Fires a [Mes Refer to [Uploading Files](/docs/reference#uploading-files) for details on attachments and `multipart/form-data` requests. Any provided files will be **appended** to the message. To remove or replace files you will have to supply the `attachments` field which specifies the files to retain on the message after edit. -> warn -> Starting with API v10, the `attachments` array must contain all attachments that should be present after edit, including **retained and new** attachments provided in the request body. +:::warn +Starting with API v10, the `attachments` array must contain all attachments that should be present after edit, including **retained and new** attachments provided in the request body. +::: -> info -> All parameters to this endpoint are optional and nullable. +:::info +All parameters to this endpoint are optional and nullable. +::: ###### JSON/Form Params @@ -899,8 +909,9 @@ Any provided files will be **appended** to the message. To remove or replace fil Delete a message. If operating on a guild channel and trying to delete a message that was not sent by the current user, this endpoint requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Message Delete](/docs/events/gateway-events#message-delete) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Bulk Delete Messages % POST /channels/{channel.id/docs/resources/channel#channel-object}/messages/bulk-delete @@ -908,11 +919,13 @@ Delete multiple messages in a single request. This endpoint can only be used on Any message IDs given that do not exist or are invalid will count towards the minimum and maximum message count (currently 2 and 100 respectively). -> warn -> This endpoint will not delete messages older than 2 weeks, and will fail with a 400 BAD REQUEST if any message provided is older than that or if any duplicate message IDs are provided. +:::warn +This endpoint will not delete messages older than 2 weeks, and will fail with a 400 BAD REQUEST if any message provided is older than that or if any duplicate message IDs are provided. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params diff --git a/docs/resources/sku.md b/docs/resources/sku.md index 376d7f157c..93ede3526b 100644 --- a/docs/resources/sku.md +++ b/docs/resources/sku.md @@ -69,8 +69,9 @@ The `flags` field can be used to differentiate user and server subscriptions wit Returns all SKUs for a given application. -> info -> Because of how our SKU and subscription systems work, you will see two SKUs for your subscription offering. For integration and testing entitlements for Subscriptions, you should use the SKU with `type: 5`. +:::info +Because of how our SKU and subscription systems work, you will see two SKUs for your subscription offering. For integration and testing entitlements for Subscriptions, you should use the SKU with `type: 5`. +::: ```json [ diff --git a/docs/resources/soundboard.md b/docs/resources/soundboard.md index 9ba06d792b..1cb9504d0f 100644 --- a/docs/resources/soundboard.md +++ b/docs/resources/soundboard.md @@ -95,11 +95,13 @@ Returns a [soundboard sound](/docs/resources/soundboard#soundboard-sound-object) Create a new soundboard sound for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [soundboard sound](/docs/resources/soundboard#soundboard-sound-object) object on success. Fires a [Guild Soundboard Sound Create](/docs/events/gateway-events#guild-soundboard-sound-create) Gateway event. -> info -> Soundboard sounds have a max file size of 512kb and a max duration of 5.2 seconds. +:::info +Soundboard sounds have a max file size of 512kb and a max duration of 5.2 seconds. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -115,11 +117,13 @@ Create a new soundboard sound for the guild. Requires the `CREATE_GUILD_EXPRESSI Modify the given soundboard sound. For sounds created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other sounds, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [soundboard sound](/docs/resources/soundboard#soundboard-sound-object) object on success. Fires a [Guild Soundboard Sound Update](/docs/events/gateway-events#guild-soundboard-sound-update) Gateway event. -> warn -> All parameters to this endpoint are optional. +:::warn +All parameters to this endpoint are optional. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -134,5 +138,6 @@ Modify the given soundboard sound. For sounds created by the current user, requi Delete the given soundboard sound. For sounds created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other sounds, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Soundboard Sound Delete](/docs/events/gateway-events#guild-soundboard-sound-delete) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: diff --git a/docs/resources/stage-instance.md b/docs/resources/stage-instance.md index 0b19c99001..494f4eaff7 100644 --- a/docs/resources/stage-instance.md +++ b/docs/resources/stage-instance.md @@ -67,8 +67,9 @@ Creates a new Stage instance associated to a Stage channel. Returns that [Stage Requires the user to be a moderator of the Stage channel. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -92,8 +93,9 @@ Updates fields of an existing Stage instance. Returns the updated [Stage instanc Requires the user to be a moderator of the Stage channel. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -108,5 +110,6 @@ Deletes the Stage instance. Returns `204 No Content`. Fires a [Stage Instance De Requires the user to be a moderator of the Stage channel. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: diff --git a/docs/resources/sticker.md b/docs/resources/sticker.md index eba6d9ab53..0f008837c8 100644 --- a/docs/resources/sticker.md +++ b/docs/resources/sticker.md @@ -132,14 +132,17 @@ Create a new sticker for the guild. Send a `multipart/form-data` body. Requires Every guilds has five free sticker slots by default, and each Boost level will grant access to more slots. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: -> warn -> Lottie stickers can only be uploaded on guilds that have either the `VERIFIED` and/or the `PARTNERED` [guild feature](/docs/resources/guild#guild-object-guild-features). +:::warn +Lottie stickers can only be uploaded on guilds that have either the `VERIFIED` and/or the `PARTNERED` [guild feature](/docs/resources/guild#guild-object-guild-features). +::: -> warn -> Uploaded stickers are constrained to 5 seconds in length for animated stickers, and 320 x 320 pixels. +:::warn +Uploaded stickers are constrained to 5 seconds in length for animated stickers, and 320 x 320 pixels. +::: ###### Form Params @@ -154,11 +157,13 @@ Every guilds has five free sticker slots by default, and each Boost level will g Modify the given sticker. For stickers created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other stickers, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [sticker](/docs/resources/sticker#sticker-object) object on success. Fires a [Guild Stickers Update](/docs/events/gateway-events#guild-stickers-update) Gateway event. -> info -> All parameters to this endpoint are optional. +:::info +All parameters to this endpoint are optional. +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -172,5 +177,6 @@ Modify the given sticker. For stickers created by the current user, requires eit Delete the given sticker. For stickers created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other stickers, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Stickers Update](/docs/events/gateway-events#guild-stickers-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: diff --git a/docs/resources/subscription.md b/docs/resources/subscription.md index 6e7f233866..2b148cef60 100644 --- a/docs/resources/subscription.md +++ b/docs/resources/subscription.md @@ -49,8 +49,9 @@ If the user cancels the subscription, the subscription will enter the `ENDING` s | ENDING | 1 | Subscription is active but will not renew. | | INACTIVE | 2 | Subscription is inactive and not being charged. | -> info -> Subscription status should not be used to grant perks. Use [entitlements](/docs/resources/entitlement#entitlement-object) as an indication of whether a user should have access to a specific SKU. See our guide on [Implementing App Subscriptions](/docs/monetization/implementing-app-subscriptions) for more information. +:::info +Subscription status should not be used to grant perks. Use [entitlements](/docs/resources/entitlement#entitlement-object) as an indication of whether a user should have access to a specific SKU. See our guide on [Implementing App Subscriptions](/docs/monetization/implementing-app-subscriptions) for more information. +::: Subscriptions can start and change between any of these statuses within the current period. A subscription can be `ACTIVE` outside its current period or `INACTIVE` within its current period. diff --git a/docs/resources/user.md b/docs/resources/user.md index 5d59a58233..9491063cb3 100644 --- a/docs/resources/user.md +++ b/docs/resources/user.md @@ -195,8 +195,9 @@ Returns a [user](/docs/resources/user#user-object) object for a given user ID. Modify the requester's user account settings. Returns a [user](/docs/resources/user#user-object) object on success. Fires a [User Update](/docs/events/gateway-events#user-update) Gateway event. -> info -> All parameters to this endpoint are optional. +:::info +All parameters to this endpoint are optional. +::: ###### JSON Params @@ -226,8 +227,9 @@ Returns a list of partial [guild](/docs/resources/guild#guild-object) objects th } ``` -> info -> This endpoint returns 200 guilds by default, which is the maximum number of guilds a non-bot user can join. Therefore, pagination is **not needed** for integrations that need to get a list of the users' guilds. +:::info +This endpoint returns 200 guilds by default, which is the maximum number of guilds a non-bot user can join. Therefore, pagination is **not needed** for integrations that need to get a list of the users' guilds. +::: ###### Query String Params @@ -250,8 +252,9 @@ Leave a guild. Returns a 204 empty response on success. Fires a [Guild Delete](/ Create a new DM channel with a user. Returns a [DM channel](/docs/resources/channel#channel-object) object (if one already exists, it will be returned instead). -> warn -> You should not use this endpoint to DM everyone in a server about something. DMs should generally be initiated by a user action. If you open a significant amount of DMs too quickly, your bot may be rate limited or blocked from opening new ones. +:::warn +You should not use this endpoint to DM everyone in a server about something. DMs should generally be initiated by a user action. If you open a significant amount of DMs too quickly, your bot may be rate limited or blocked from opening new ones. +::: ###### JSON Params @@ -263,8 +266,9 @@ Create a new DM channel with a user. Returns a [DM channel](/docs/resources/chan Create a new group DM channel with multiple users. Returns a [DM channel](/docs/resources/channel#channel-object) object. This endpoint was intended to be used with the now-deprecated GameBridge SDK. Fires a [Channel Create](/docs/events/gateway-events#channel-create) Gateway event. -> warn -> This endpoint is limited to 10 active group DMs. +:::warn +This endpoint is limited to 10 active group DMs. +::: ###### JSON Params diff --git a/docs/resources/webhook.md b/docs/resources/webhook.md index 379037f609..ac19f4914f 100644 --- a/docs/resources/webhook.md +++ b/docs/resources/webhook.md @@ -33,8 +33,9 @@ Used to represent a webhook. ###### Webhook Types -> info -> These types don't include [webhook events](/docs/events/webhook-events), which are outgoing webhooks sent to your app by Discord. See [Webhook Events](/docs/events/webhook-events) for details. +:::info +These types don't include [webhook events](/docs/events/webhook-events), which are outgoing webhooks sent to your app by Discord. See [Webhook Events](/docs/events/webhook-events) for details. +::: | Value | Name | Description | |-------|------------------|----------------------------------------------------------------------------------------------------------------| @@ -117,8 +118,9 @@ An error will be returned if a webhook name (`name`) is not valid. A webhook nam - It does not contain the substrings `clyde` or `discord` (case-insensitive) - It follows the nickname guidelines in the [Usernames and Nicknames](/docs/resources/user#usernames-and-nicknames) documentation, with an exception that webhook names can be up to 80 characters -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -150,11 +152,13 @@ Same as above, except this call does not require authentication and returns no u Modify a webhook. Requires the `MANAGE_WEBHOOKS` permission. Returns the updated [webhook](/docs/resources/webhook#webhook-object) object on success. Fires a [Webhooks Update](/docs/events/gateway-events#webhooks-update) Gateway event. -> info -> All parameters to this endpoint are optional +:::info +All parameters to this endpoint are optional +::: -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ###### JSON Params @@ -172,8 +176,9 @@ Same as above, except this call does not require authentication, does not accept Delete a webhook permanently. Requires the `MANAGE_WEBHOOKS` permission. Returns a `204 No Content` response on success. Fires a [Webhooks Update](/docs/events/gateway-events#webhooks-update) Gateway event. -> info -> This endpoint supports the `X-Audit-Log-Reason` header. +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: ## Delete Webhook with Token % DELETE /webhooks/{webhook.id/docs/resources/webhook#webhook-object}/{webhook.token/docs/resources/webhook#webhook-object} @@ -183,14 +188,17 @@ Same as above, except this call does not require authentication. Refer to [Uploading Files](/docs/reference#uploading-files) for details on attachments and `multipart/form-data` requests. Returns a message or `204 No Content` depending on the `wait` query parameter. -> info -> Note that when sending a message, you must provide a value for at **least one of** `content`, `embeds`, `components`, `file`, or `poll`. +:::info +Note that when sending a message, you must provide a value for at **least one of** `content`, `embeds`, `components`, `file`, or `poll`. +::: -> info -> If the webhook channel is a forum or media channel, you must provide either `thread_id` in the query string params, or `thread_name` in the JSON/form params. If `thread_id` is provided, the message will send in that thread. If `thread_name` is provided, a thread with that name will be created in the channel. +:::info +If the webhook channel is a forum or media channel, you must provide either `thread_id` in the query string params, or `thread_name` in the JSON/form params. If `thread_id` is provided, the message will send in that thread. If `thread_name` is provided, a thread with that name will be created in the channel. +::: -> warn -> Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and using `allowed_mentions` to prevent unexpected mentions. +:::warn +Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and using `allowed_mentions` to prevent unexpected mentions. +::: ###### Query String Params @@ -223,8 +231,9 @@ Refer to [Uploading Files](/docs/reference#uploading-files) for details on attac \*\* See [Uploading Files](/docs/reference#uploading-files) for details. -> info -> For the webhook embed objects, you can set every field except `type` (it will be `rich` regardless of if you try to set it), `provider`, `video`, and any `height`, `width`, or `proxy_url` values for images. +:::info +For the webhook embed objects, you can set every field except `type` (it will be `rich` regardless of if you try to set it), `provider`, `video`, and any `height`, `width`, or `proxy_url` values for images. +::: ## Execute Slack-Compatible Webhook % POST /webhooks/{webhook.id/docs/resources/webhook#webhook-object}/{webhook.token/docs/resources/webhook#webhook-object}/slack @@ -267,11 +276,13 @@ When the `content` field is edited, the `mentions` array in the message object w Refer to [Uploading Files](/docs/reference#uploading-files) for details on attachments and `multipart/form-data` requests. Any provided files will be **appended** to the message. To remove or replace files you will have to supply the `attachments` field which specifies the files to retain on the message after edit. -> warn -> Starting with API v10, the `attachments` array must contain all attachments that should be present after edit, including **retained and new** attachments provided in the request body. +:::warn +Starting with API v10, the `attachments` array must contain all attachments that should be present after edit, including **retained and new** attachments provided in the request body. +::: -> info -> All parameters to this endpoint are optional and nullable. +:::info +All parameters to this endpoint are optional and nullable. +::: ###### Query String Params diff --git a/docs/rich-presence/best-practices.md b/docs/rich-presence/best-practices.md index 8e818164c5..6226538724 100644 --- a/docs/rich-presence/best-practices.md +++ b/docs/rich-presence/best-practices.md @@ -83,8 +83,9 @@ Ready to launch a Rich Presence integration for your game? If so, we recommend l #### Joining -> info -> Since all Activities presence data has an **Ask to Join** button, Join Invites are only applicable when building with the [Game SDK](/docs/rich-presence/using-with-the-game-sdk) +:::info +Since all Activities presence data has an **Ask to Join** button, Join Invites are only applicable when building with the [Game SDK](/docs/rich-presence/using-with-the-game-sdk) +::: - Have you successfully implemented join invites for your game if applicable? - Does the state of the invite properly represent the party/group in-game with regards to: diff --git a/docs/rich-presence/overview.mdx b/docs/rich-presence/overview.mdx index 9b6f37828f..bc9956d303 100644 --- a/docs/rich-presence/overview.mdx +++ b/docs/rich-presence/overview.mdx @@ -20,8 +20,9 @@ There are three options when integrating Rich Presence. Depending on what you're All SDKs use similar underlying primitives (like the [`SET_ACTIVITY` RPC command](/docs/topics/rpc#setactivity)), so a lot is the same between them. But there are a few differences, like feature compatibility, which is covered in the sections below. -> info -> Rich Presence data appears publicly on your Discord profile, so during development you should use a test account that only belongs to your private development server(s). +:::info +Rich Presence data appears publicly on your Discord profile, so during development you should use a test account that only belongs to your private development server(s). +::: ### Discord Social SDK @@ -41,8 +42,9 @@ After a user joins an Activity, Rich Presence can be used to dynamically show da ### Game SDK -> warn -> **The Game SDK has been archived.**
We recommend using the [Discord Social SDK](/docs/discord-social-sdk/overview) for new projects.
Existing projects using the Game SDK will continue to work, but we encourage you to migrate to the [Discord Social SDK](/docs/discord-social-sdk/overview) for new features and updates. +:::warn +**The Game SDK has been archived.**
We recommend using the [Discord Social SDK](/docs/discord-social-sdk/overview) for new projects.
Existing projects using the Game SDK will continue to work, but we encourage you to migrate to the [Discord Social SDK](/docs/discord-social-sdk/overview) for new features and updates. +::: The [Game SDK](/docs/developer-tools/game-sdk) makes it easier to build 3rd party games and integrate them with Discord. While many features of the Game SDK are deprecated, it can still be used for a few use cases (like integrating Rich Presence!). @@ -60,8 +62,9 @@ To add custom assets for Rich Presence, navigate to your [app's settings](https: The Rich Presence invite image appears when [invites](/docs/developer-tools/game-sdk#sendinvite) are sent for a 3rd party game or app using the [Game SDK](/docs/rich-presence/overview#game-sdk). After uploading an invite image for your app, you can see a preview of it to the right (under "IRL Invite Image Example"). -> info -> The invite image can be ignored if you're building using the [Embedded App SDK](/docs/rich-presence/overview#embedded-app-sdk). Invites sent using the Embedded App SDK's[`openInviteDialog()`](/docs/developer-tools/embedded-app-sdk#openinvitedialog) use the Activity's cover art. +:::info +The invite image can be ignored if you're building using the [Embedded App SDK](/docs/rich-presence/overview#embedded-app-sdk). Invites sent using the Embedded App SDK's[`openInviteDialog()`](/docs/developer-tools/embedded-app-sdk#openinvitedialog) use the Activity's cover art. +::: ![Rich Presence invite image in app settings](images/rich-presence-invite-image.png) @@ -71,8 +74,9 @@ Up to 300 custom assets can be added for your app to use when setting Rich Prese If you need more than 300 custom assets or want to use images stored somewhere else, you can also [specify an external URL](/docs/events/gateway-events#activity-object-activity-asset-image) as long it still has the proper dimensions and size. -> info -> For tips on choosing assets, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices#have-interesting-expressive-art). +:::info +For tips on choosing assets, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices#have-interesting-expressive-art). +::: When uploading Rich Presence assets, **the asset keys will automatically be changed to lowercase**. You can see this reflected in your app's settings after saving a newly-uploaded asset, and should keep it in mind when referencing any asset keys in your code. @@ -80,8 +84,9 @@ When uploading Rich Presence assets, **the asset keys will automatically be chan ### Using the Visualizer -> warn -> The Rich Presence visualizer currently uses an outdated Discord UI, but can still be helpful as a quick-and-dirty reference for what your Rich Presence data will look like in Discord. +:::warn +The Rich Presence visualizer currently uses an outdated Discord UI, but can still be helpful as a quick-and-dirty reference for what your Rich Presence data will look like in Discord. +::: In your app's settings, there's a Rich Presence visualizer to make it easier to see what your uploaded [assets](/docs/rich-presence/overview#assets) will look like in the context of a Discord profile. To access the visualizer, navigate to your [app's settings](https://discord.com/developers/applications) and click **Rich Presence** on the left-hand sidebar. On the **Visualizer** page, you can fill out some custom strings, party information, and select your uploaded assets to see a preview. diff --git a/docs/rich-presence/using-with-the-discord-social-sdk.mdx b/docs/rich-presence/using-with-the-discord-social-sdk.mdx index 4515ab1dfe..1be1a8ed86 100644 --- a/docs/rich-presence/using-with-the-discord-social-sdk.mdx +++ b/docs/rich-presence/using-with-the-discord-social-sdk.mdx @@ -7,8 +7,9 @@ sidebar_label: Using with the Discord Social SDK When developing a game, the [Discord Social SDK](/docs/discord-social-sdk/overview) makes it easy to integrate Rich Presence to display details about what a user is up to inside of your game or social experience. -> info -> Not sure if you should be building with the Discord Social SDK? Read through [Choosing an SDK](/docs/rich-presence/overview#choosing-an-sdk) to understand your options when integrating Rich Presence with your app. +:::info +Not sure if you should be building with the Discord Social SDK? Read through [Choosing an SDK](/docs/rich-presence/overview#choosing-an-sdk) to understand your options when integrating Rich Presence with your app. +::: ## Understanding Rich Presence Data @@ -17,8 +18,9 @@ Before we dig in, it's helpful to understand what Rich Presence data you can set ![Graphical representation of the legend for rich presence details](images/rp-legend.png) -> info -> For tips on designing Rich Presence, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices). +:::info +For tips on designing Rich Presence, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices). +::: ## Setting Rich Presence Data diff --git a/docs/rich-presence/using-with-the-embedded-app-sdk.mdx b/docs/rich-presence/using-with-the-embedded-app-sdk.mdx index 02ce0f58cf..c215b87469 100644 --- a/docs/rich-presence/using-with-the-embedded-app-sdk.mdx +++ b/docs/rich-presence/using-with-the-embedded-app-sdk.mdx @@ -8,8 +8,9 @@ When developing an [Activity](/docs/activities/overview), the [Embedded App SDK] Rich Presence data can be thought of as an extension of your Activity—and leveling it up just a *little* makes it more interesting and relevant to the user playing your Activity (and their friends that might want to jump in and play). This guide provides an overview of the platform and technical knowledge you need to integrate Rich Presence with your existing Activity. -> info -> Not sure if you should be building with the Embedded App SDK? Read through [Choosing an SDK](/docs/rich-presence/overview#choosing-an-sdk) to understand your options when integrating Rich Presence with your app. +:::info +Not sure if you should be building with the Embedded App SDK? Read through [Choosing an SDK](/docs/rich-presence/overview#choosing-an-sdk) to understand your options when integrating Rich Presence with your app. +::: The rest of the guide assumes you've already developed an [app](/docs/quick-start/overview-of-apps) that can launch an Activity. If you aren't at that point quite yet, you should follow the guide on [building your first Activity](/docs/activities/building-an-activity) before continuing. @@ -54,8 +55,9 @@ To request the scope, your [`authorize()`](/docs/developer-tools/embedded-app-sd -> info -> The following example only focuses on calling `authorize()`. Follow the [Building an Activity guide](/docs/activities/building-an-activity) for more details on topics like installing and instantiating the Embedded App SDK. +:::info +The following example only focuses on calling `authorize()`. Follow the [Building an Activity guide](/docs/activities/building-an-activity) for more details on topics like installing and instantiating the Embedded App SDK. +::: ```js // Authorize with Discord Client @@ -80,8 +82,9 @@ Below is a table with many of the available fields for the activity partial. Som #### Activity partial object -> info -> All of the fields on the partial object are optional and nullable +:::info +All of the fields on the partial object are optional and nullable +::: | field | type | description | |------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| @@ -102,8 +105,9 @@ To create this sort of Rich Presence, here is what the `setActivity()` code woul -> info -> The following example only focuses on using `setActivity()`. Follow the [Building an Activity guide](/docs/activities/building-an-activity) for more details on topics like instantiating the Embedded App SDK and authenticating users. +:::info +The following example only focuses on using `setActivity()`. Follow the [Building an Activity guide](/docs/activities/building-an-activity) for more details on topics like instantiating the Embedded App SDK and authenticating users. +::: ```js await discordSdk.commands.setActivity({ activity: { @@ -135,8 +139,9 @@ As mentioned in the [Rich Presence overview](/docs/rich-presence/overview#assets -> info -> The following example only focuses on using `setActivity()`. Follow the [Building an Activity guide](/docs/activities/building-an-activity) for more details on topics like instantiating the Embedded App SDK and authenticating users. +:::info +The following example only focuses on using `setActivity()`. Follow the [Building an Activity guide](/docs/activities/building-an-activity) for more details on topics like instantiating the Embedded App SDK and authenticating users. +::: ```js await discordSdk.commands.setActivity({ activity: { diff --git a/docs/rich-presence/using-with-the-game-sdk.mdx b/docs/rich-presence/using-with-the-game-sdk.mdx index 1be5e836c4..336bd12878 100644 --- a/docs/rich-presence/using-with-the-game-sdk.mdx +++ b/docs/rich-presence/using-with-the-game-sdk.mdx @@ -4,15 +4,17 @@ sidebar_label: Using with the Game SDK # Using Rich Presence with the Game SDK -> warn -> **The Game SDK has been archived.**
We recommend using the [Discord Social SDK](/docs/discord-social-sdk/overview) for new projects.
Existing projects using the Game SDK will continue to work, but we encourage you to migrate to the [Discord Social SDK](/docs/discord-social-sdk/overview) for new features and updates. +:::warn +**The Game SDK has been archived.**
We recommend using the [Discord Social SDK](/docs/discord-social-sdk/overview) for new projects.
Existing projects using the Game SDK will continue to work, but we encourage you to migrate to the [Discord Social SDK](/docs/discord-social-sdk/overview) for new features and updates. +::: The [Game SDK](/docs/developer-tools/game-sdk) helps you build 3rd party games and integrate them with Discord. One of its specialties is making it easy to bring your game's data to Discord using [Rich Presence](/docs/rich-presence/overview), which this guide will cover. Before we dig in, make sure you've gone through the guide on [Getting Started with the Game SDK](/docs/developer-tools/game-sdk#getting-started). This guide expects that you've already [downloaded the SDK](/docs/developer-tools/game-sdk#step-1-get-the-sdk), [configured your app](/docs/developer-tools/game-sdk#step-2-create-your-app), and [gotten up and running with a basic example](/docs/developer-tools/game-sdk#step-3-start-coding). -> info -> Not sure if you should be building with the Game SDK? Read through [Choosing an SDK](/docs/rich-presence/overview#choosing-an-sdk) to understand your options when integrating Rich Presence. +:::info +Not sure if you should be building with the Game SDK? Read through [Choosing an SDK](/docs/rich-presence/overview#choosing-an-sdk) to understand your options when integrating Rich Presence. +::: ## Understanding Rich Presence Data @@ -37,8 +39,9 @@ Note that this layout may be subject to change without warning. This information impaired eyesight to understand the potential layout of this information in a user interface. -> info -> For tips on designing Rich Presence, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices). +:::info +For tips on designing Rich Presence, take a look at the [Rich Presence best practices guide](/docs/rich-presence/best-practices). +::: ## Activities Manager @@ -66,8 +69,9 @@ When calling `UpdateActivity()`, you'll be expected to pass the [activity](/docs Below are the fields we'll be paying attention to as we're passing presence data for a user. -> info -> All fields are optional and nullable +:::info +All fields are optional and nullable +::: | Name | Type | Description | |------------|--------------------------------------------------------------------------------|-----------------------------------------------------------------| @@ -83,8 +87,9 @@ Below are the fields we'll be paying attention to as we're passing presence data Now let's take a look at a code example for updating presence data. -> info -> All of the code samples in this guide are in C#, but there are some similar examples in other languages [on GitHub](https://github.com/msciotti/discord-game-sdk-test-apps). +:::info +All of the code samples in this guide are in C#, but there are some similar examples in other languages [on GitHub](https://github.com/msciotti/discord-game-sdk-test-apps). +::: Our code sample in this section is based on the data from the example from before: @@ -94,8 +99,9 @@ The **Ask to Join** button will be covered more in the following sections, but i -> info -> The following example only focuses on using `UpdateActivity()`. You can read the [Getting Started](/docs/developer-tools/game-sdk#getting-started) and [Using the SDK](/docs/developer-tools/game-sdk#using-the-sdk) sections for more general information about using the Game SDK. +:::info +The following example only focuses on using `UpdateActivity()`. You can read the [Getting Started](/docs/developer-tools/game-sdk#getting-started) and [Using the SDK](/docs/developer-tools/game-sdk#using-the-sdk) sections for more general information about using the Game SDK. +::: ```cs var activity = new Discord.Activity diff --git a/docs/topics/certified-devices.md b/docs/topics/certified-devices.md index 71391083e8..c373674187 100644 --- a/docs/topics/certified-devices.md +++ b/docs/topics/certified-devices.md @@ -48,8 +48,9 @@ Each time you update, send a full array of `devices`, sorted by your preferred p For each device in the `SET_CERTIFIED_DEVICES` payload, there is an `id` field. This `id` should be the Windows device's UUID, retrieved through the native Windows API. You'll get back something that looks like `{0.0.1.00000000}.{6cff2b76-44a8-46b9-b528-262ad8609d9f}`. -> info -> On macOS, the `id` will be the name of the device. +:::info +On macOS, the `id` will be the name of the device. +::: ###### Microphone Id Example diff --git a/docs/topics/oauth2.md b/docs/topics/oauth2.md index 608b82d380..6e0d78718c 100644 --- a/docs/topics/oauth2.md +++ b/docs/topics/oauth2.md @@ -14,8 +14,9 @@ The first step in implementing OAuth2 is [registering a developer application](h | https://discord.com/api/oauth2/token | Token URL | | https://discord.com/api/oauth2/token/revoke | [Token Revocation](https://tools.ietf.org/html/rfc7009) URL | -> warn -> In accordance with the relevant RFCs, the token and token revocation URLs will **only** accept a content type of `application/x-www-form-urlencoded`. JSON content is not permitted and will return an error. +:::warn +In accordance with the relevant RFCs, the token and token revocation URLs will **only** accept a content type of `application/x-www-form-urlencoded`. JSON content is not permitted and will return an error. +::: ###### OAuth2 Scopes @@ -52,9 +53,10 @@ These are a list of all the OAuth2 scopes that Discord supports. Some scopes req | voice | allows your app to connect to voice on user's behalf and see all the voice members - requires Discord approval | | webhook.incoming | this generates a webhook that is returned in the oauth token response for authorization code grants | -> info -> In order to add a user to a guild, your bot has to already belong to that guild. -> `role_connections.write` cannot be used with the [Implicit grant type](/docs/topics/oauth2#implicit-grant). +:::info +In order to add a user to a guild, your bot has to already belong to that guild. +`role_connections.write` cannot be used with the [Implicit grant type](/docs/topics/oauth2#implicit-grant). +::: ## State and Security @@ -170,8 +172,9 @@ To disable an access or refresh token, you can revoke it by making a `POST` requ - `token` - the access token or refresh token to revoke - `token_type_hint` *(optional)* - the `token` parameter's type—either `access_token` or `refresh_token` -> warn -> When you revoke a token, any active access or refresh tokens associated with that authorization will be revoked, regardless of the `token` and `token_type_hint` values you pass in. +:::warn +When you revoke a token, any active access or refresh tokens associated with that authorization will be revoked, regardless of the `token` and `token_type_hint` values you pass in. +::: ```python import requests @@ -219,8 +222,9 @@ The client credential flow is a quick and easy way for bot developers to get the You can specify scopes with the `scope` parameter, which is a list of [OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) separated by spaces: -> info -> Team applications are limited to the `identify` and `applications.commands.update` scope, because teams are not bound to a specific user. +:::info +Team applications are limited to the `identify` and `applications.commands.update` scope, because teams are not bound to a specific user. +::: ###### Client Credentials Token Request Example @@ -264,8 +268,9 @@ Discord's API provides bot users, which are a separate type of user dedicated to ### Bot vs User Accounts -> warn -> Developers must abide by the [terms of service](https://support-dev.discord.com/hc/articles/8562894815383-Discord-Developer-Terms-of-Service), which includes refraining from automating standard user accounts (generally called "self-bots") outside of the OAuth2/bot API. +:::warn +Developers must abide by the [terms of service](https://support-dev.discord.com/hc/articles/8562894815383-Discord-Developer-Terms-of-Service), which includes refraining from automating standard user accounts (generally called "self-bots") outside of the OAuth2/bot API. +::: Bot users have a few differences compared to standard Discord users: diff --git a/docs/topics/permissions.md b/docs/topics/permissions.md index 2593a1978b..e648a30b84 100644 --- a/docs/topics/permissions.md +++ b/docs/topics/permissions.md @@ -2,15 +2,17 @@ Permissions are a way to limit and grant certain abilities to users in Discord. A set of base permissions can be configured at the guild level for different roles. When these roles are attached to users, they grant or revoke specific privileges within the guild. Along with the guild-level permissions, Discord also supports permission overwrites that can be assigned to individual roles or members on a per-channel basis. -> info -> [Application command permissions](/docs/interactions/application-commands#permissions) allow you to enable or disable specific commands for entire channels in addition to individual roles or users. +:::info +[Application command permissions](/docs/interactions/application-commands#permissions) allow you to enable or disable specific commands for entire channels in addition to individual roles or users. +::: Permissions are stored in a variable-length integer serialized into a string, and are calculated using bitwise operations. For example, the permission value `123` will be serialized as `"123"`. For long-term stability, it's recommended to deserialize the permissions using your preferred languages' Big Integer libraries. The total permissions integer can be determined by OR-ing (`|`) together each individual value, and flags can be checked using AND (`&`) operations. In API v8 and above, all permissions are serialized as strings, including the `allow` and `deny` fields in overwrites. Any new permissions are rolled back into the base field. -> info -> In [API v6 (now deprecated)](/docs/reference), the `permissions`, `allow`, and `deny` fields in roles and overwrites are still serialized as a number; however, these numbers shall not grow beyond 31 bits. During the remaining lifetime of API v6, all new permission bits will only be introduced in `permissions_new`, `allow_new`, and `deny_new`. These `_new` fields are just for response serialization; requests with these fields should continue to use the original `permissions`, `allow`, and `deny` fields, which accept both string or number values. +:::info +In [API v6 (now deprecated)](/docs/reference), the `permissions`, `allow`, and `deny` fields in roles and overwrites are still serialized as a number; however, these numbers shall not grow beyond 31 bits. During the remaining lifetime of API v6, all new permission bits will only be introduced in `permissions_new`, `allow_new`, and `deny_new`. These `_new` fields are just for response serialization; requests with these fields should continue to use the original `permissions`, `allow`, and `deny` fields, which accept both string or number values. +::: ```python # Permissions value that can Send Messages (0x800) and Add Reactions (0x40): diff --git a/docs/topics/rate-limits.md b/docs/topics/rate-limits.md index 6f86965e1b..9035afd466 100644 --- a/docs/topics/rate-limits.md +++ b/docs/topics/rate-limits.md @@ -2,8 +2,9 @@ Rate limits exist across Discord's APIs to prevent spam, abuse, and service overload. Limits are applied to individual bots and users both on a per-route basis and globally. Individuals are determined using a request's authentication—for example, a bot token for a bot. -> info -> Because rate limits depend on a variety of factors and are subject to change, **rate limits should not be hard coded into your app**. Instead, your app should parse [response headers](/docs/topics/rate-limits#header-format-rate-limit-header-examples) to prevent hitting the limit, and to respond accordingly in case you do. +:::info +Because rate limits depend on a variety of factors and are subject to change, **rate limits should not be hard coded into your app**. Instead, your app should parse [response headers](/docs/topics/rate-limits#header-format-rate-limit-header-examples) to prevent hitting the limit, and to respond accordingly in case you do. +::: **Per-route rate limits** exist for many individual endpoints, and may include the HTTP method (`GET`, `POST`, `PUT`, or `DELETE`). In some cases, per-route limits will be shared across a set of similar endpoints, indicated in the `X-RateLimit-Bucket` header. It's recommended to use this header as a unique identifier for a rate limit, which will allow you to group shared limits as you encounter them. @@ -11,8 +12,9 @@ During calculation, per-route rate limits often account for top-level resources **Global rate limits** apply to the total number of requests a bot or user makes, independent of any per-route limits. You can read more on [global rate limits](/docs/topics/rate-limits#global-rate-limit) below. -> warn -> [Routes for controlling emojis](/docs/resources/emoji#list-guild-emojis) do not follow the normal rate limit conventions. These routes are specifically limited on a per-guild basis to prevent abuse. This means that the quota returned by our APIs may be inaccurate, and you may encounter 429s. +:::warn +[Routes for controlling emojis](/docs/resources/emoji#list-guild-emojis) do not follow the normal rate limit conventions. These routes are specifically limited on a per-guild basis to prevent abuse. This means that the quota returned by our APIs may be inaccurate, and you may encounter 429s. +::: ## Header Format diff --git a/docs/topics/rpc.md b/docs/topics/rpc.md index 10fbe9cf4a..d40e7f87b5 100644 --- a/docs/topics/rpc.md +++ b/docs/topics/rpc.md @@ -1,7 +1,8 @@ # RPC -> danger -> For now, RPC is in a private beta. We are not currently accepting any new developers into the program at this time. +:::danger +For now, RPC is in a private beta. We are not currently accepting any new developers into the program at this time. +::: All Discord clients have an RPC server running on localhost that allows control over local Discord clients. @@ -483,13 +484,14 @@ Used to change voice settings of users in voice channels | volume? | integer | set the volume of user (defaults to 100, min 0, max 200) | | mute? | boolean | set the mute state of the user | -> info -> In the current release, we only support a single modifier of voice settings at a time over RPC. -> If an app changes voice settings, it will lock voice settings so that other apps connected simultaneously -> lose the ability to change voice settings. Settings reset to what they were before being changed after the -> controlling app disconnects. When an app that has previously set voice settings connects, the client will swap -> to that app's configured voice settings and lock voice settings again. This is a temporary situation that will -> be changed in the future. +:::info +In the current release, we only support a single modifier of voice settings at a time over RPC. +If an app changes voice settings, it will lock voice settings so that other apps connected simultaneously +lose the ability to change voice settings. Settings reset to what they were before being changed after the +controlling app disconnects. When an app that has previously set voice settings connects, the client will swap +to that app's configured voice settings and lock voice settings again. This is a temporary situation that will +be changed in the future. +::: ###### Pan Object @@ -547,8 +549,9 @@ Used to join and leave voice channels, group dms, or dms. Returns the [Get Chann | force | boolean | forces a user to join a voice channel | | navigate | boolean | after joining the voice channel, navigate to it in the client | -> warn -> When trying to join the user to a voice channel, you will receive a `5003` error coded response if the user is already in a voice channel. The `force` parameter should only be specified in response to the case where a user is already in a voice channel and they have **approved** to be moved by your app to a new voice channel. +:::warn +When trying to join the user to a voice channel, you will receive a `5003` error coded response if the user is already in a voice channel. The `force` parameter should only be specified in response to the case where a user is already in a voice channel and they have **approved** to be moved by your app to a new voice channel. +::: ###### Example Select Voice Channel Command Payload @@ -735,13 +738,14 @@ Used to join and leave text channels, group dms, or dms. Returns the [Get Channe #### SET_VOICE_SETTINGS -> info -> In the current release, we only support a single modifier of voice settings at a time over RPC. -> If an app changes voice settings, it will lock voice settings so that other apps connected simultaneously -> lose the ability to change voice settings. Settings reset to what they were before being changed after the -> controlling app disconnects. When an app that has previously set voice settings connects, the client will swap -> to that app's configured voice settings and lock voice settings again. This is a temporary situation that will -> be changed in the future. +:::info +In the current release, we only support a single modifier of voice settings at a time over RPC. +If an app changes voice settings, it will lock voice settings so that other apps connected simultaneously +lose the ability to change voice settings. Settings reset to what they were before being changed after the +controlling app disconnects. When an app that has previously set voice settings connects, the client will swap +to that app's configured voice settings and lock voice settings again. This is a temporary situation that will +be changed in the future. +::: When setting voice settings, all fields are optional. Only passed fields are updated. @@ -992,8 +996,9 @@ Used to update a user's Rich Presence. ###### Set Activity Argument Structure -> info -> When using `SET_ACTIVITY`, the `activity` object is limited to a `type` of Playing (`0`), Listening (`2`), Watching (`3`), or Competing (`5`). +:::info +When using `SET_ACTIVITY`, the `activity` object is limited to a `type` of Playing (`0`), Listening (`2`), Watching (`3`), or Competing (`5`). +::: | Field | Type | Description | |----------|----------------------------------------------------------------|-----------------------------------------| diff --git a/docs/topics/teams.md b/docs/topics/teams.md index 29e573173a..7c3893521f 100644 --- a/docs/topics/teams.md +++ b/docs/topics/teams.md @@ -10,8 +10,9 @@ To create or be a member on a team, you must [enable 2FA for your Discord accoun Once you create a team, you'll land on the **Team Information** page where you can fill out details and start inviting other Discord users to join your team. Since users added to a team have access to any apps that team owns, use caution when adding new team members. -> info -> Only the team Owner and team Admins can invite or remove additional users. +:::info +Only the team Owner and team Admins can invite or remove additional users. +::: ## Adding Apps to a Team @@ -27,8 +28,9 @@ To create a new app that belongs to a team, select the team from the **Team** dr To transfer an existing app to a team, navigate to the [Application](https://discord.com/developers/applications) that you want to transfer. At the bottom of the app's **General Information** page, click "Transfer App to Team". -> danger -> Once an app has been transferred to a team, it _cannot_ be transferred back. +:::danger +Once an app has been transferred to a team, it _cannot_ be transferred back. +::: ![Screenshot of where to find the button to transfer an Application to a team](images/transfer-app-to-team.png) diff --git a/docs/topics/threads.md b/docs/topics/threads.md index cd9bdff416..f0951e7af3 100644 --- a/docs/topics/threads.md +++ b/docs/topics/threads.md @@ -67,8 +67,9 @@ Threads generally inherit permissions from the parent channel (e.g. if you can a Three permission bits are specific to threads: `CREATE_PUBLIC_THREADS`, `CREATE_PRIVATE_THREADS`, and `SEND_MESSAGES_IN_THREADS`. -> warn -> The `SEND_MESSAGES` permission has no effect in threads; users must have `SEND_MESSAGES_IN_THREADS` to talk in a thread. +:::warn +The `SEND_MESSAGES` permission has no effect in threads; users must have `SEND_MESSAGES_IN_THREADS` to talk in a thread. +::: Private threads are similar to Group DMs, but in a guild: You must be invited to the thread to be able to view or participate in it, or be a moderator (`MANAGE_THREADS` permission). @@ -100,8 +101,9 @@ Membership is tracked in an array of [thread member](/docs/resources/channel#thr ### Syncing for other users -> info -> These require the `GUILD_MEMBERS` [Gateway Intent](/docs/events/gateway#gateway-intents) +:::info +These require the `GUILD_MEMBERS` [Gateway Intent](/docs/events/gateway#gateway-intents) +::: - An API `GET` call to [`/channels//thread-members`](/docs/resources/channel#list-thread-members) which returns an array of [thread member](/docs/resources/channel#thread-member-object) objects. - The [Thread Members Update](/docs/events/gateway-events#thread-members-update) Gateway Event which will include all users who were added to or removed from a thread by an action. @@ -158,8 +160,9 @@ When an app is added to a private thread, it likely doesn't have that thread in Private threads are only synced to you if you are a member or a moderator. Whenever a user is added to a private thread, the Gateway also sends a [Thread Create](/docs/events/gateway-events#thread-create) event. This ensures the client always has a non-null value for that thread. -> info -> The `THREAD_CREATE` event is also sent when the user is a moderator (and thus would already have the channel in memory). +:::info +The `THREAD_CREATE` event is also sent when the user is a moderator (and thus would already have the channel in memory). +::: #### Gaining Access to Public Threads @@ -181,8 +184,9 @@ When an app loses access to a channel, the Gateway does **not** send it [Thread If an app wanted to track when it lost access to any thread, it's possible but difficult as it would need to handle all cases correctly. Usually, events that cause permission changes are a [Guild Role Update](/docs/events/gateway-events#guild-role-update), [Guild Member Update](/docs/events/gateway-events#guild-member-update) or [Channel Update](/docs/events/gateway-events#channel-update) event. -> info -> Discord's clients check their permissions *first* when performing an action. That way, even if it has some stale data, it does not end up acting on it. +:::info +Discord's clients check their permissions *first* when performing an action. That way, even if it has some stale data, it does not end up acting on it. +::: Additionally, when a user or app loses access to a channel, they are not removed from the thread and will continue to be reported as a member of that thread. However, they will **not** receive any new Gateway events unless they are removed from the thread, in which case they will receive a [Thread Members Update](/docs/events/gateway-events#thread-members-update) event. @@ -199,15 +203,17 @@ A `GUILD_FORUM` (type `15`) channel is similar to a `GUILD_TEXT` channel, except Messages cannot be sent directly in forum channels. -> info -> More information about forum channels and how they appear in Discord can be found in the [Forum Channels FAQ](https://support.discord.com/hc/en-us/articles/6208479917079-Forum-Channels-FAQ#h_01G69FJQWTWN88HFEHK7Z6X79N) +:::info +More information about forum channels and how they appear in Discord can be found in the [Forum Channels FAQ](https://support.discord.com/hc/en-us/articles/6208479917079-Forum-Channels-FAQ#h_01G69FJQWTWN88HFEHK7Z6X79N) +::: ## Media Channels A `GUILD_MEDIA` (type `16`) channel is similar to a `GUILD_FORUM` channel in that only threads can be created in them. Unless otherwise noted, threads in media channels behave in the same way as in forum channels - meaning they use the same endpoints and receive the same Gateway events. More information about media channels and how they appear in Discord can be found in the [media channels Help Center Article](https://creator-support.discord.com/hc/en-us/articles/14346342766743). -> warn -> `GUILD_MEDIA` channels are in beta and still being actively developed. The API and other technical details are subject to change. +:::warn +`GUILD_MEDIA` channels are in beta and still being actively developed. The API and other technical details are subject to change. +::: ### Creating Threads in Forum and Media Channels diff --git a/docs/topics/voice-connections.mdx b/docs/topics/voice-connections.mdx index f2ef19ea09..6a6af958cf 100644 --- a/docs/topics/voice-connections.mdx +++ b/docs/topics/voice-connections.mdx @@ -65,10 +65,12 @@ With this information, we can move on to establishing a voice WebSocket connecti When sending a voice state update to change channels within the same guild, it is possible to receive a VOICE_SERVER_UPDATE with the same `endpoint` as the previous VOICE_SERVER_UPDATE. The `token` will be changed and you cannot re-use the previous session during a channel change, even if the endpoint remains the same. -> info -> Bot users respect the voice channel's user limit, if set. When the voice channel is full, you will not receive -> the Voice State Update or Voice Server Update events in response to your own Voice State Update. Having `MANAGE_CHANNELS` -> permission bypasses this limit and allows you to join regardless of the channel being full or not. +:::info +Bot users respect the voice channel's user limit, if set. When the voice channel is full, you will not receive +the Voice State Update or Voice Server Update events in response to your own Voice State Update. Having `MANAGE_CHANNELS` +permission bypasses this limit and allows you to join regardless of the channel being full or not. +::: + ## Establishing a Voice Websocket Connection @@ -105,8 +107,9 @@ The voice server should respond with an [Opcode 2 Ready](/docs/topics/opcodes-an } ``` -> danger -> `heartbeat_interval` here is an erroneous field and should be ignored. The correct `heartbeat_interval` value comes from the Hello payload. +:::danger +`heartbeat_interval` here is an erroneous field and should be ignored. The correct `heartbeat_interval` value comes from the Hello payload. +::: ## Heartbeating @@ -460,11 +463,13 @@ The following flags can be used as a bitwise mask. For example `5` would be prio } ``` -> warn -> You must send at least one [Opcode 5 Speaking](/docs/topics/opcodes-and-status-codes#voice) payload before sending voice data, or you will be disconnected with an invalid SSRC error. +:::warn +You must send at least one [Opcode 5 Speaking](/docs/topics/opcodes-and-status-codes#voice) payload before sending voice data, or you will be disconnected with an invalid SSRC error. +::: -> info -> The `delay` property should be set to `0` for bots that use the voice gateway. +:::info +The `delay` property should be set to `0` for bots that use the voice gateway. +::: ### Voice Data Interpolation diff --git a/docs/tutorials/configuring-app-metadata-for-linked-roles.md b/docs/tutorials/configuring-app-metadata-for-linked-roles.md index 93deeeeaf9..66be5ae77b 100644 --- a/docs/tutorials/configuring-app-metadata-for-linked-roles.md +++ b/docs/tutorials/configuring-app-metadata-for-linked-roles.md @@ -6,8 +6,9 @@ Apps can define their own [role connection metadata](/docs/resources/application This tutorial walks through building a Discord app in JavaScript with linked roles support. -> info -> All of the sample code used in this tutorial can be found in the [`linked-roles-sample` GitHub repo](https://github.com/discord/linked-roles-sample) +:::info +All of the sample code used in this tutorial can be found in the [`linked-roles-sample` GitHub repo](https://github.com/discord/linked-roles-sample) +::: --- @@ -15,15 +16,17 @@ This tutorial walks through building a Discord app in JavaScript with linked rol The first thing we’ll do is create an app through the [developer dashboard](https://discord.com/developers/applications). If you already have an app created, you can jump right to the [Running your app](/docs/tutorials/configuring-app-metadata-for-linked-roles#running-your-app) section. -> info -> Basic steps to create an app are outlined below, but a more detailed walkthrough is in the [Getting Started guide](/docs/quick-start/getting-started). +:::info +Basic steps to create an app are outlined below, but a more detailed walkthrough is in the [Getting Started guide](/docs/quick-start/getting-started). +::: - Navigate to the [developer dashboard](https://discord.com/developers/applications) - Click **New Application** in the upper right corner, then select a name and create your app - Click on the **Bot** tab on the left sidebar. On that page, click **Reset Token** and store the token somewhere safe (like in a password manager) -> warn -> Bot tokens are used to authorize API requests and carry your bot's permissions, making them highly sensitive. Never share your token or check it into any kind of version control. +:::warn +Bot tokens are used to authorize API requests and carry your bot's permissions, making them highly sensitive. Never share your token or check it into any kind of version control. +::: ### Adding scopes @@ -33,8 +36,9 @@ Apps need approval from installing users to perform actions inside of Discord. S - Check the `bot` scope - After the scope is selected, you should see a **Generated URL** which can be used to install your app -> info -> See a list of all [OAuth2 scopes](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes), or read more on [user permissions](https://discord.com/developers/docs/topics/permissions) in the documentation. +:::info +See a list of all [OAuth2 scopes](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes), or read more on [user permissions](https://discord.com/developers/docs/topics/permissions) in the documentation. +::: ### Installing your app @@ -50,8 +54,9 @@ All of the code used in the example app can be found in the [GitHub repository]( This guide uses Glitch, which allows you to quickly clone and develop an app from within your browser. There are also instructions on developing locally using ngrok in the README if you'd prefer. -> info -> While Glitch is great for development and testing, [it has technical limitations](https://help.glitch.com/kb/article/17-technical-restrictions/) so other hosting providers should be considered for production apps. +:::info +While Glitch is great for development and testing, [it has technical limitations](https://help.glitch.com/kb/article/17-technical-restrictions/) so other hosting providers should be considered for production apps. +::: To start, [remix (or clone) the Glitch project 🎏](https://glitch.com/edit/#!/remix/linked-role-discord-bot) @@ -81,8 +86,9 @@ All of the files for the project are on the left-hand side. Here's a quick glimp There's already some code in your `server.js` file, but you’ll need your app’s token and ID to make requests. All of your credentials can be stored directly in the `.env` file. -> warn -> It bears repeating that you should never check any credentials or secrets into source control. The getting started project's `.gitignore` comes pre-loaded with `.env` to prevent it. +:::warn +It bears repeating that you should never check any credentials or secrets into source control. The getting started project's `.gitignore` comes pre-loaded with `.env` to prevent it. +::: First, copy your bot user’s token from earlier and paste it in the `DISCORD_TOKEN` variable in your `.env` file. @@ -98,8 +104,9 @@ Go back to the OAuth2 -> General tab in the Discord developer portal, and add a Go to the General Information tab in the developer portal, and scroll down to the `Linked Roles Verification Url` field. Paste the base URL to your Glitch app, add the `/linked-role` route, then save. -> info -> For the Glitch project used in the screenshots, the verification URL would be `https://adjoining-crawling-yamamomo.glitch.me/linked-role` +:::info +For the Glitch project used in the screenshots, the verification URL would be `https://adjoining-crawling-yamamomo.glitch.me/linked-role` +::: ![Verify endpoint](images/linked-roles-verify-endpoint.png) @@ -150,8 +157,9 @@ Give the role a name, save it, then click on `Links`. Click the `Add requirement To acquire your newly created role, click the server name in the upper left corner of the screen, and select `Linked Roles`. Click on your role, and it will present the opportunity to connect your account. -> info -> When you connect your account, one of the scopes requested in the OAuth flow is `role_connections.write`, which is required for an app to update a user's role connection information. +:::info +When you connect your account, one of the scopes requested in the OAuth flow is `role_connections.write`, which is required for an app to update a user's role connection information. +::: ![Connect accounts](images/linked-roles-connect-account.png) diff --git a/docs/tutorials/developing-a-user-installable-app.mdx b/docs/tutorials/developing-a-user-installable-app.mdx index 6ce4112b81..6004ff4874 100644 --- a/docs/tutorials/developing-a-user-installable-app.mdx +++ b/docs/tutorials/developing-a-user-installable-app.mdx @@ -31,8 +31,9 @@ Before we dig in, you'll need the project code from the [sample app repository]( ``` -> info -> We'll be developing our app locally with a little help from [ngrok](https://ngrok.com/), but you can use your preferred development environment. +:::info +We'll be developing our app locally with a little help from [ngrok](https://ngrok.com/), but you can use your preferred development environment. +::: If you don't have [NodeJS](https://nodejs.org/en/download/) installed, install that first. @@ -68,8 +69,9 @@ After you create your app, you'll land on the **General Overview** page of the a While we're in your app's settings, we'll want to get a few sensitive values for your app, like its token and ID. -> warn -> Your token is used to authorize API requests and carry your app's permissions, so they are *highly* sensitive. Make sure to never share your token or check it into any kind of version control. +:::warn +Your token is used to authorize API requests and carry your app's permissions, so they are *highly* sensitive. Make sure to never share your token or check it into any kind of version control. +::: Back in your project folder, rename the `.env.sample` file to `.env`. `.env` is where we'll store all of your app's credentials. @@ -109,8 +111,9 @@ Under the **Default Install Settings** section: - For **User Install**, add the `applications.commands` scope - For **Guild Install**, add the `applications.commands` scope and `bot` scope. When you select `bot`, a new **Permissions** menu will appear to select the bot user's permissions. Select any permissions that you may want for your app—for now, I'll just select `Send Messages`. -> info -> Permissions for a bot user are very similar to permissions for other Discord users. Details about permissions, and a list of available permissions is on the [Permissions](/docs/topics/permissions#permissions-bitwise-permission-flags) page. +:::info +Permissions for a bot user are very similar to permissions for other Discord users. Details about permissions, and a list of available permissions is on the [Permissions](/docs/topics/permissions#permissions-bitwise-permission-flags) page. +::: After you've selected the scopes and permissions for your app, click **Save Changes**. @@ -157,8 +160,9 @@ We'll be setting up four commands for our sample app that all have *slightly* di | `/profile` | Get information about your game inventory and progress | `USER_INSTALL` | `GUILD`, `BOT_DM`, `PRIVATE_CHANNEL` | | `/link` | Link your game account to Discord | `USER_INSTALL` | `BOT_DM` | -> info -> The supported installation contexts for a command affects which interaction contexts you can set. Specifically, the `PRIVATE_CHANNEL` interaction context can only be included in `contexts` if `USER_INSTALL` is included in `integration_types` for the command. Read details in the [documentation](/docs/interactions/application-commands#contexts). +:::info +The supported installation contexts for a command affects which interaction contexts you can set. Specifically, the `PRIVATE_CHANNEL` interaction context can only be included in `contexts` if `USER_INSTALL` is included in `integration_types` for the command. Read details in the [documentation](/docs/interactions/application-commands#contexts). +::: The payloads for our app's commands are in `commands.js` in the project folder in case you want to change any values or see what the command's context fields (`integration_types` and `contexts`) look like for each of the commands in the table above. @@ -198,8 +202,9 @@ npm run start There should be some output indiciating your app is running on port 3000. Behind the scenes, our app is ready to handle interactions from Discord, which includes verifying security request headers and responding to `PING` requests. We're skipping over a lot of the details in this tutorial, but details about preparing apps for interactions is in the [Interactions Overview](/docs/interactions/overview#preparing-for-interactions) documentation. -> info -> By default, the server will listen to requests sent to port 3000, but if you want to change the port, you can specify a `PORT` variable in your `.env` file. +:::info +By default, the server will listen to requests sent to port 3000, but if you want to change the port, you can specify a `PORT` variable in your `.env` file. +::: Next, we'll start our ngrok tunnel. If you don't have ngrok installed locally, you can install it by following the instructions on the [ngrok download page](https://ngrok.com/download). @@ -220,8 +225,9 @@ Go to your [app's settings](https://discord.com/developers/applications) and on Click **Save Changes** and if all is well, your Interactions Endpoint URL should be verified by Discord. -> info -> If you have troubles verifying your endpoint, make sure both ngrok and your app is running on the same port, and that you've copied the ngrok URL correctly +:::info +If you have troubles verifying your endpoint, make sure both ngrok and your app is running on the same port, and that you've copied the ngrok URL correctly +::: ### Understanding metadata for interactions @@ -273,8 +279,9 @@ With interaction context, something to keep in mind in `BOT_DM` is only the *DM The keys in the object are the relevant installation context(s) (`GUILD_INSTALL`/`"0"` and/or `USER_INSTALL`/`"1"`). The values depend on the key, but for `USER_INSTALL` the key will always be the ID of the user that authorized your app. -> info -> `authorizing_integration_owners` is not the same as the user that triggered the interaction. Information about the user that triggered the interaction is in the `user` object. +:::info +`authorizing_integration_owners` is not the same as the user that triggered the interaction. Information about the user that triggered the interaction is in the `user` object. +::: Understanding the authorization owner can be helpful when handling interactions from message components for apps installed to a user, which is discussed more in the [message component interactions](/docs/tutorials/developing-a-user-installable-app#using-metadata-for-message-component-interactions) section. Or you can find technical details in the [Authorizing Integration Owners](/docs/interactions/receiving-and-responding#interaction-object-authorizing-integration-owners-object) documentation. diff --git a/docs/tutorials/hosting-on-cloudflare-workers.md b/docs/tutorials/hosting-on-cloudflare-workers.md index 251173e968..95e6196c02 100644 --- a/docs/tutorials/hosting-on-cloudflare-workers.md +++ b/docs/tutorials/hosting-on-cloudflare-workers.md @@ -35,8 +35,9 @@ To start, we'll create the app through the [Discord Developer Dashboard](https:/ - Now click on the **Bot** tab on the left sidebar. - Grab the `token` for your bot, and store it somewhere safe (I like to put these tokens in a password manager like [1password](https://1password.com/) or [lastpass](https://www.lastpass.com/)). -> warn -> For security reasons, you can only view your bot token once. If you misplace your token, you'll have to generate a new one. +:::warn +For security reasons, you can only view your bot token once. If you misplace your token, you'll have to generate a new one. +::: ## Adding bot permissions @@ -53,8 +54,9 @@ Now we'll configure the bot with [permissions](/docs/topics/permissions) require Cloudflare Workers are a convenient way to host Discord apps due to the free tier, simple development model, and automatically managed environment (no VMs!). -> warn -> When using Cloudflare Workers, your app won't be able to access non-ephemeral CDN media. For example, trying to fetch an image like `https://cdn.discordapp.com/attachments/1234/56789/my_image.png` would result in a `403` error. Cloudflare Workers are still able to access ephemeral CDN media. +:::warn +When using Cloudflare Workers, your app won't be able to access non-ephemeral CDN media. For example, trying to fetch an image like `https://cdn.discordapp.com/attachments/1234/56789/my_image.png` would result in a `403` error. Cloudflare Workers are still able to access ephemeral CDN media. +::: - Visit the [Cloudflare Dashboard](https://dash.cloudflare.com/) - Click on the `Workers` tab, and create a new service using the same name as your Discord bot @@ -72,8 +74,9 @@ $ wrangler secret put DISCORD_APPLICATION_ID You'll also need the Guild ID for the server where your app is installed. This can be found in the URL when you visit any channel in that server. -> info -> For example, if my URL was `https://discord.com/channels/123456/789101112`, the Guild ID is the first number—in this case **`123456`**. +:::info +For example, if my URL was `https://discord.com/channels/123456/789101112`, the Guild ID is the first number—in this case **`123456`**. +::: Once you know your Guild ID, set that variable as well: @@ -83,8 +86,9 @@ $ wrangler secret put DISCORD_TEST_GUILD_ID ## Running locally -> info -> This depends on the beta version of the `wrangler` package, which better supports ESM on Cloudflare Workers. +:::info +This depends on the beta version of the `wrangler` package, which better supports ESM on Cloudflare Workers. +::: Let's start by cloning the repository and installing dependencies. This requires at least v16 of [Node.js](https://nodejs.org/en/): @@ -340,8 +344,9 @@ router.post('/', async (request, env) => { ## Next steps -> info -> In case you need to reference any of the code, you can find the repo [on GitHub](https://github.com/discord/cloudflare-sample-app) +:::info +In case you need to reference any of the code, you can find the repo [on GitHub](https://github.com/discord/cloudflare-sample-app) +::: With your app built and deployed, you can start customizing it to be your own: diff --git a/docs/tutorials/upgrading-to-application-commands.md b/docs/tutorials/upgrading-to-application-commands.md index e041d18a44..1d61c03143 100644 --- a/docs/tutorials/upgrading-to-application-commands.md +++ b/docs/tutorials/upgrading-to-application-commands.md @@ -10,8 +10,9 @@ This guide is intended to provide developers with apps currently using message c ![Client interfaces showing the different types of application commands](images/command-types.png) -> info -> If you are developing an app for the first time, the [commands documentation](/docs/interactions/application-commands) may be a more helpful resource for you. +:::info +If you are developing an app for the first time, the [commands documentation](/docs/interactions/application-commands) may be a more helpful resource for you. +::: Before diving in, it’s worth noting that with the message content changes, apps can still access message content in their DMs with users, as well as when messages are sent that directly `@mentions` their bot user (since there is clear user intent that the bot can read those messages). @@ -33,8 +34,9 @@ Slash commands can appear in channels and DMs, so they’re helpful when an acti [User commands](/docs/interactions/application-commands#user-commands) are in the context menu for users, which is accessed by right-clicking or tapping on any user. They’re helpful when an action is tied to an individual user, like a moderation app adding a timeout to someone. -> info -> Within the context menus for users and messages, the `Apps` submenu will only appear if an app in that server has installed a corresponding command (whether or not an individual user can use the installed command). +:::info +Within the context menus for users and messages, the `Apps` submenu will only appear if an app in that server has installed a corresponding command (whether or not an individual user can use the installed command). +::: ### Message Commands @@ -47,8 +49,9 @@ Slash commands can appear in channels and DMs, so they’re helpful when an acti Commands can be registered via HTTP requests after an app is authorized with the `applications.commands` scope. The `applications.commands` scope is also automatically included when an app requests the `bot` scope. -> info -> There is a section on [designing commands](/docs/tutorials/upgrading-to-application-commands#designing-for-commands) below implementation details that may be helpful as you start mapping out different commands +:::info +There is a section on [designing commands](/docs/tutorials/upgrading-to-application-commands#designing-for-commands) below implementation details that may be helpful as you start mapping out different commands +::: The API endpoint to register (or create) commands is different depending on its scope: @@ -130,15 +133,17 @@ Permissions for specific roles, users, and channels can be updated by your app i Commands use the [interactions model](/docs/interactions/receiving-and-responding) through HTTP-based outgoing webhooks or the WebSocket-based [Interaction Create gateway event](/docs/events/gateway-events#interaction-create). Regardless of the transit method used to arrive, your app will receive relevant information when a Discord user triggers one of your app’s interactions. -> warn -> If you continue using Gateway events, you’ll still receive message events but the payloads will have empty string or array data for message content-related fields like `content`, `embeds`, `attachments`, and `components` while `poll` will be omitted. You can read more in the [message content intent](/docs/events/gateway#message-content-intent) section. +:::warn +If you continue using Gateway events, you’ll still receive message events but the payloads will have empty string or array data for message content-related fields like `content`, `embeds`, `attachments`, and `components` while `poll` will be omitted. You can read more in the [message content intent](/docs/events/gateway#message-content-intent) section. +::: For commands, this means that each time one of your commands is used, your app will receive information like the command name and the user who triggered it. More information about this information is below in the section on [parsing command payloads](/docs/tutorials/upgrading-to-application-commands#parsing-command-payloads). ### Adding an Interactions Endpoint URL -> info -> This step is specific to receiving interactions over HTTP. If you prefer to use the [Gateway](/docs/events/gateway), this step won't be applicable to your app. +:::info +This step is specific to receiving interactions over HTTP. If you prefer to use the [Gateway](/docs/events/gateway), this step won't be applicable to your app. +::: Before your app can receive interactions, you’ll need to set up an **Interaction Endpoint URL** in your app settings. This endpoint should be a public URL where Discord can send all interactions-related requests. @@ -147,8 +152,9 @@ However, before adding your URL to your app settings, your endpoint must be set 1. **Responding to `PING` events**: When you save a URL in your settings, Discord will send a `POST` request with `type: 1`. To acknowledge this request (and thus verify your endpoint), you should return a `200` response with a payload containing `type: 1`. More information can be found in the [Receiving an Interaction documentation](/docs/interactions/receiving-and-responding#receiving-an-interaction). 2. **Verifying request signatures**: To ensure that requests are coming from Discord, your endpoint must verify each request using the included headers, specifically `X-Signature-Ed25519` and `X-Signature-Timestamp`. If the signature fails validating, your app should return a `401` response. More information and example code can be found in the [Security and Authorization documentation](/docs/interactions/overview#setting-up-an-endpoint-validating-security-request-headers). -> info -> Many libraries on the [Community Resources page](/docs/developer-tools/community-resources#interactions) simplify verification and interaction request handling by exporting reusable functions and/or handling it automatically. +:::info +Many libraries on the [Community Resources page](/docs/developer-tools/community-resources#interactions) simplify verification and interaction request handling by exporting reusable functions and/or handling it automatically. +::: After your URL is set up to handle signature verification and `PING` requests, you can add your Interaction Endpoint URL by navigating to your app settings from the [developer portal](https://discord.com/developers/applications). On the **General Information** page, you’ll see a field for your **Interactions Endpoint URL**. @@ -166,8 +172,9 @@ As mentioned above, these include information relevant to handling the command l Since slash commands (`CHAT_INPUT` commands) are run in the context of a channel, you’ll notice that their payloads don’t contain any information about specific messages. If your app needs the message content, you can use [message commands](/docs/interactions/application-commands#message-commands) which *do* include the message content. -> info -> In the getting started guide’s repository, there’s a code sample showing [how to create and handle commands using JavaScript](https://github.com/discord/discord-example-app/blob/main/examples/command.js). +:::info +In the getting started guide’s repository, there’s a code sample showing [how to create and handle commands using JavaScript](https://github.com/discord/discord-example-app/blob/main/examples/command.js). +::: Below is an example payload your app would receive when a user invoked a global command with an option: @@ -223,8 +230,9 @@ To determine how your app should handle an incoming command-related interaction, Adding commands to your app can add discoverability and interactivity for users. While porting your app’s features, it’s worth considering how your app will be seen and used inside of the client. This section includes a handful of areas to consider when designing your app’s commands, and what happens after they’re invoked. -> info -> CLIs (Command Line Interfaces) can be a helpful analogy when designing Discord commands, their options and subcommands, and how it all fits together into one experience. A good resource for this can be the open source [Command Interface Guidelines](https://clig.dev/). +:::info +CLIs (Command Line Interfaces) can be a helpful analogy when designing Discord commands, their options and subcommands, and how it all fits together into one experience. A good resource for this can be the open source [Command Interface Guidelines](https://clig.dev/). +::: ### Choosing a Name @@ -279,8 +287,9 @@ As to where to communicate the changes, you can start with any communication cha You can also inform users about changes within the servers your app is installed in as long as it’s done in a non-intrusive way. If your app has a dedicated channel in posts, that would be a good place. -> warn -> Don’t DM all users in a server where your app is installed. It could get your app rate limited, but more importantly, it can be pretty intrusive and might lead to your app being uninstalled. +:::warn +Don’t DM all users in a server where your app is installed. It could get your app rate limited, but more importantly, it can be pretty intrusive and might lead to your app being uninstalled. +::: #### Example