From 43170f8867ad0398dc00eeaf47093bda8ce85940 Mon Sep 17 00:00:00 2001 From: shay Date: Thu, 27 Jun 2024 14:13:17 -0400 Subject: [PATCH] Update User-Installed Apps Docs for GA (#6958) * update user install docs * add 5 max followup callout * add change log * pass through application * remove lingering preview labels * update wording in tutorial * update defaults * api update * wrong wording oop * Update docs/Change_Log.md Co-authored-by: vee * Update docs/resources/Application.md Co-authored-by: vee --------- Co-authored-by: vee --- docs/Change_Log.md | 35 ++++++- docs/interactions/Application_Commands.md | 95 +++++++++---------- docs/interactions/Receiving_and_Responding.md | 3 + docs/resources/Application.md | 42 +++++++- .../Developing_a_User_Installable_App.mdx | 7 +- 5 files changed, 121 insertions(+), 61 deletions(-) diff --git a/docs/Change_Log.md b/docs/Change_Log.md index e73e50d19c..4582824965 100644 --- a/docs/Change_Log.md +++ b/docs/Change_Log.md @@ -1,5 +1,37 @@ # Change Log +## User-Installed Apps General Availability + +#### June 27, 2024 + +> danger +> This entry includes breaking changes + +Back in March, we announced [the beta for user-installed apps](#DOCS_CHANGE_LOG/userinstallable-apps-preview). After listening and making updates based on feedback from developers and modmins, we're excited to announce that user-installed apps are now considered generally available and can be used in all servers (regardless of size). + +With this update, there are a few API and behavioral updates for user-installed apps. + +###### API Updates + +- `user_id` has been removed from the `interaction_metadata` field on messages. Instead, you can use the `id` field in the nested `user` object. See the [Message Interaction Metadata Object](#DOCS_RESOURCES_CHANNEL/message-interaction-metadata-object) for details. +- User-installed apps are now limited to creating a maximum of 5 [follow-ups](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/followup-messages) when responding to interactions. This only affects the [Create Followup Message endpoint](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/create-followup-message), and apps installed to the server are unaffected. +- On [Interactions](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-structure), the value of `authorizing_integration_owners` is now correctly serialized as a string. Previously, the `"0"` value was incorrectly serialized as a number. +- `app_permissions` on [Interactions](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-structure) now correctly represents the permissions for user-installed apps. Previously, the value was incorrect for user-installed apps. +- Updating a message can result in a `400` response if the content of the message was blocked by AutoMod, which may be particularly important for [deferred messages](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/responding-to-an-interaction). +- Interaction responses are no longer forced to be ephemeral for servers with over 25 members. + +###### New `Use External Apps` Permission + +A new [`USE_EXTERNAL_APPS` (`1 << 50`) permission](#DOCS_TOPICS_PERMISSIONS/permissions-bitwise-permission-flags) was added, and is enabled for servers by default. The new permission lets modmins control whether user-installed apps can post public replies in a server. If `Use External Apps` is disabled and your app is *not* installed to the server, your app’s responses will be ephemeral for the end user. + +Read more in the [Moderating Apps on Discord Help Center article](https://support.discord.com/hc/en-us/articles/23957313048343-Moderating-Apps-on-Discord#h_01HZQQQEADYVN2CM4AX4EZGKHM). + +###### Updated Defaults for New Apps + +- Newly-created apps now default to having both "User Install" *and* "Guild Install" [installation contexts](#DOCS_RESOURCES_APPLICATION/installation-context) enabled. This can be updated in the **Installation** tab in an [app's settings](https://discord.com/developers/applications). +- Newly-created apps now default to using the "Discord Provided Link" [install link](#DOCS_RESOURCES_APPLICATION/install-links). This can be updated in the **Installation** tab in an [app's settings](https://discord.com/developers/applications). +- If Discord Provided Link is selected as the install link type, `application.commands` scope is added to both installation contexts. + ## Premium Apps: New Premium Button Style & Deep Linking URL Schemes #### June 17, 2024 @@ -76,9 +108,6 @@ You can find the export at the bottom of the `Monetization → Analytics` tab of #### March 18, 2024 -> preview -> User-installable apps are currently in preview. During the preview, there are major [limitations and known bugs](#DOCS_CHANGE_LOG/march-18-2024-limitations-and-known-issues), and API details are subject to change. - Apps can now be installed to users—making them easier to install, discover, and access across Discord. User-installed apps can be used across all of a user's servers, within their (G)DMs, and in DMs with the app's bot user. When creating or updating your app, you can choose which installation types your app supports on the **Installation** page in your [app's settings](https://discord.com/developers/applications). To quickly get started, you can follow the new [Developing a User-Installable App tutorial](#DOCS_TUTORIALS_DEVELOPING_A_USER_INSTALLABLE_APP) or read details about the new changes below. diff --git a/docs/interactions/Application_Commands.md b/docs/interactions/Application_Commands.md index 0f4efb8756..ed787a22d9 100644 --- a/docs/interactions/Application_Commands.md +++ b/docs/interactions/Application_Commands.md @@ -12,24 +12,24 @@ Application commands are native ways to interact with apps in the Discord client ###### Application Command Structure -| Field | Type | Description | Valid Types | -|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------| -| id | snowflake | Unique ID of command | all | -| type? | one of [application command type](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types) | [Type of command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types), defaults to `1` | all | -| application_id | snowflake | ID of the parent application | all | -| guild_id? | snowflake | Guild ID of the command, if not global | all | -| name | string | [Name of command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-naming), 1-32 characters | all | -| name_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for `name` field. Values follow the same restrictions as `name` | all | -| description | string | Description for `CHAT_INPUT` commands, 1-100 characters. Empty string for `USER` and `MESSAGE` commands | all | -| description_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for `description` field. Values follow the same restrictions as `description` | all | -| options? \* | array of [application command option](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-option-structure) | Parameters for the command, max of 25 | CHAT_INPUT | -| default_member_permissions | ?string | Set of [permissions](#DOCS_TOPICS_PERMISSIONS) represented as a bit set | all | -| dm_permission? | boolean | **Deprecated (use `contexts` instead)**; Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. | all | -| default_permission? | ?boolean | Not recommended for use as field will soon be deprecated. Indicates whether the command is enabled by default when the app is added to a guild, defaults to `true` | all | -| nsfw? | boolean | Indicates whether the command is [age-restricted](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/agerestricted-commands), defaults to `false` | all | -| integration_types? | list of [integration types](#DOCS_RESOURCES_APPLICATION/application-object-application-integration-types) | [In preview](#DOCS_CHANGE_LOG/userinstallable-apps-preview). [Installation context(s)](#DOCS_RESOURCES_APPLICATION/installation-context) where the command is available, only for globally-scoped commands. Defaults to `GUILD_INSTALL` (`0`) | all | -| contexts? | ?list of [interaction context types](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) | [In preview](#DOCS_CHANGE_LOG/userinstallable-apps-preview). [Interaction context(s)](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) where the command can be used, only for globally-scoped commands. By default, all interaction context types included for new commands. | all | -| version | snowflake | Autoincrementing version identifier updated during substantial record changes | all | +| Field | Type | Description | Valid Types | +|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------| +| id | snowflake | Unique ID of command | all | +| type? | one of [application command type](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types) | [Type of command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types), defaults to `1` | all | +| application_id | snowflake | ID of the parent application | all | +| guild_id? | snowflake | Guild ID of the command, if not global | all | +| name | string | [Name of command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-naming), 1-32 characters | all | +| name_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for `name` field. Values follow the same restrictions as `name` | all | +| description | string | Description for `CHAT_INPUT` commands, 1-100 characters. Empty string for `USER` and `MESSAGE` commands | all | +| description_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for `description` field. Values follow the same restrictions as `description` | all | +| options? \* | array of [application command option](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-option-structure) | Parameters for the command, max of 25 | CHAT_INPUT | +| default_member_permissions | ?string | Set of [permissions](#DOCS_TOPICS_PERMISSIONS) represented as a bit set | all | +| dm_permission? | boolean | **Deprecated (use `contexts` instead)**; Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. | all | +| default_permission? | ?boolean | Not recommended for use as field will soon be deprecated. Indicates whether the command is enabled by default when the app is added to a guild, defaults to `true` | all | +| nsfw? | boolean | Indicates whether the command is [age-restricted](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/agerestricted-commands), defaults to `false` | all | +| integration_types? | list of [integration types](#DOCS_RESOURCES_APPLICATION/application-object-application-integration-types) | [Installation contexts](#DOCS_RESOURCES_APPLICATION/installation-context) where the command is available, only for globally-scoped commands. Defaults to your app's [configured contexts](#DOCS_RESOURCES_APPLICATION/installation-context/setting-supported-installation-contexts) | all | +| contexts? | ?list of [interaction context types](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) | [Interaction context(s)](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) where the command can be used, only for globally-scoped commands. By default, all interaction context types included for new commands. | all | +| version | snowflake | Autoincrementing version identifier updated during substantial record changes | all | \* `options` can only be set for application commands of type `CHAT_INPUT`. @@ -247,9 +247,6 @@ Detailed documentation about application command endpoints and their parameters ## Contexts -> preview -> The user installation context for apps is currently in a public preview and is subject to change. Read details and limitations about the public preview in the [change log](#DOCS_CHANGE_LOG/userinstallable-apps-preview). - Commands have two sets of contexts on the [application command object](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object) that let you to configure when and where it can be used: - `integration_types` defines the **[installation contexts](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/installation-context)** that a command supports - `contexts` defines the **[interaction contexts](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/interaction-contexts)** where a command can be used @@ -1123,19 +1120,19 @@ Edit a global command. Returns `200` and an [application command](#DOCS_INTERACT ###### JSON Params -| Field | Type | Description | -|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| name? | string | [Name of command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-naming), 1-32 characters | -| name_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for the `name` field. Values follow the same restrictions as `name` | -| description? | string | 1-100 character description | -| description_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for the `description` field. Values follow the same restrictions as `description` | -| options? | array of [application command option](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-option-structure) | the parameters for the command | -| default_member_permissions? | ?string | Set of [permissions](#DOCS_TOPICS_PERMISSIONS) represented as a bit set | -| dm_permission? | ?boolean | **Deprecated (use `contexts` instead)**; Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. | -| default_permission? | boolean | Replaced by `default_member_permissions` and will be deprecated in the future. Indicates whether the command is enabled by default when the app is added to a guild. Defaults to `true` | -| integration_types? | list of [integration types](#DOCS_RESOURCES_APPLICATION/application-object-application-integration-types) | [In preview](#DOCS_CHANGE_LOG/userinstallable-apps-preview). [Installation context(s)](#DOCS_RESOURCES_APPLICATION/installation-context) where the command is available | -| contexts? | list of [interaction context types](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) | [In preview](#DOCS_CHANGE_LOG/userinstallable-apps-preview). [Interaction context(s)](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) where the command can be used | -| nsfw? | boolean | Indicates whether the command is [age-restricted](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/agerestricted-commands) | +| Field | Type | Description | +|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| name? | string | [Name of command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-naming), 1-32 characters | +| name_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for the `name` field. Values follow the same restrictions as `name` | +| description? | string | 1-100 character description | +| description_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for the `description` field. Values follow the same restrictions as `description` | +| options? | array of [application command option](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-option-structure) | the parameters for the command | +| default_member_permissions? | ?string | Set of [permissions](#DOCS_TOPICS_PERMISSIONS) represented as a bit set | +| dm_permission? | ?boolean | **Deprecated (use `contexts` instead)**; Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. | +| default_permission? | boolean | Replaced by `default_member_permissions` and will be deprecated in the future. Indicates whether the command is enabled by default when the app is added to a guild. Defaults to `true` | +| integration_types? | list of [integration types](#DOCS_RESOURCES_APPLICATION/application-object-application-integration-types) | [Installation context(s)](#DOCS_RESOURCES_APPLICATION/installation-context) where the command is available | +| contexts? | list of [interaction context types](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) | [Interaction context(s)](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) where the command can be used | +| nsfw? | boolean | Indicates whether the command is [age-restricted](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/agerestricted-commands) | ## Delete Global Application Command % DELETE /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/commands/{command.id#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object} @@ -1219,21 +1216,21 @@ Takes a list of application commands, overwriting the existing command list for ###### JSON Params -| Field | Type | Description | -|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| id? | snowflake | ID of the command, if known | -| name | string | [Name of command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-naming), 1-32 characters | -| name_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for the `name` field. Values follow the same restrictions as `name` | -| description | string | 1-100 character description | -| description_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for the `description` field. Values follow the same restrictions as `description` | -| options? | array of [application command option](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-option-structure) | Parameters for the command | -| default_member_permissions? | ?string | Set of [permissions](#DOCS_TOPICS_PERMISSIONS) represented as a bit set | -| dm_permission? | ?boolean | **Deprecated (use `contexts` instead)**; Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. | -| default_permission? | boolean | Replaced by `default_member_permissions` and will be deprecated in the future. Indicates whether the command is enabled by default when the app is added to a guild. Defaults to `true` | -| integration_types | list of [integration types](#DOCS_RESOURCES_APPLICATION/application-object-application-integration-types) | [In preview](#DOCS_CHANGE_LOG/userinstallable-apps-preview). [Installation context(s)](#DOCS_RESOURCES_APPLICATION/installation-context) where the command is available, defaults to `GUILD_INSTALL` (`[0]`) | -| contexts | list of [interaction context types](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) | [In preview](#DOCS_CHANGE_LOG/userinstallable-apps-preview). [Interaction context(s)](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) where the command can be used, defaults to all contexts `[0,1,2]` | -| type? | one of [application command type](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types) | Type of command, defaults `1` if not set | -| nsfw? | boolean | Indicates whether the command is [age-restricted](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/agerestricted-commands) | +| Field | Type | Description | +|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| id? | snowflake | ID of the command, if known | +| name | string | [Name of command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-naming), 1-32 characters | +| name_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for the `name` field. Values follow the same restrictions as `name` | +| description | string | 1-100 character description | +| description_localizations? | ?dictionary with keys in [available locales](#DOCS_REFERENCE/locales) | Localization dictionary for the `description` field. Values follow the same restrictions as `description` | +| options? | array of [application command option](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-option-structure) | Parameters for the command | +| default_member_permissions? | ?string | Set of [permissions](#DOCS_TOPICS_PERMISSIONS) represented as a bit set | +| dm_permission? | ?boolean | **Deprecated (use `contexts` instead)**; Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible. | +| default_permission? | boolean | Replaced by `default_member_permissions` and will be deprecated in the future. Indicates whether the command is enabled by default when the app is added to a guild. Defaults to `true` | +| integration_types | list of [integration types](#DOCS_RESOURCES_APPLICATION/application-object-application-integration-types) | [Installation context(s)](#DOCS_RESOURCES_APPLICATION/installation-context) where the command is available, defaults to `GUILD_INSTALL` (`[0]`) | +| contexts | list of [interaction context types](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) | [Interaction context(s)](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) where the command can be used, defaults to all contexts `[0,1,2]` | +| type? | one of [application command type](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types) | Type of command, defaults `1` if not set | +| nsfw? | boolean | Indicates whether the command is [age-restricted](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/agerestricted-commands) | ## Get Guild Application Command Permissions % GET /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/commands/permissions diff --git a/docs/interactions/Receiving_and_Responding.md b/docs/interactions/Receiving_and_Responding.md index eb6b08f61e..2999011a71 100644 --- a/docs/interactions/Receiving_and_Responding.md +++ b/docs/interactions/Receiving_and_Responding.md @@ -348,6 +348,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`) + 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. `flags` can be set to `64` to mark the message as ephemeral, except when it is the first followup message to a deferred Interactions Response. In that case, the `flags` field will be ignored, and the ephemerality of the message will be determined by the `flags` value in your original ACK. diff --git a/docs/resources/Application.md b/docs/resources/Application.md index cf0b977626..d29b211dce 100644 --- a/docs/resources/Application.md +++ b/docs/resources/Application.md @@ -140,14 +140,10 @@ Where an app can be installed, also called its supported [installation contexts] ## Installation Context -> preview -> The user installation context for apps is currently in a public preview and is subject to change. Read details and limitations about the public preview in the [change log](#DOCS_CHANGE_LOG/userinstallable-apps-preview). - An app's installation context defines how it's installed: to a server, to a user, or both. The installation context affects how your app can be seen and used within Discord. For example, apps installed only to a user can't take actions in a server, and apps installed only to a server can't be accessed within a user's DMs. - #### Server Context Apps installed in a server context (server-installed apps) must be authorized by a server member with the [`MANAGE_GUILD`](#DOCS_TOPICS_PERMISSIONS/permissions-bitwise-permission-flags) permission. Server-installed apps are *visible* to all members of the server, but other factors (like [command permissions](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/permissions)) determine where and when specific members can interact with the app. @@ -169,6 +165,44 @@ You can update which installation contexts your app supports in your [app's sett > 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 + +Install links provide an easy way for users to install your app in Discord. If you have an install link configured, an "Add App" button will appear in your app's profile and App Directory page which will guide the user through your app's installation flow. + +### Types of Install Links + +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`. + +#### Discord Provided Link + +The default Discord Provided Link is a short link that guides users through the installation flow with your app's [configured installation contexts](#DOCS_RESOURCES_APPLICATION/setting-supported-installation-contexts). If your app has both **User Install** and **Guild Install** enabled, the user can choose which way to install your app. + +Discord Provided Links don't have scopes or bot user permissions defined in the URL. For example: + +``` +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 + +#### Custom URL + +A Custom URL is an alternative to the Discord Provided Link that gives you more control of where users are directed when they click "Add App" on your app's profile or App Directory page. + +A Custom URL doesn't have strict limitations, but is commonly an [OAuth2 `/authorize` URL](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-urls) that has defined scopes, permissions, and an installation context (`integration_type`). + +### Configuring an Install Link and Default Install Settings + +You can configure your app's install link in your [app's settings](https://discord.com/developers/applications). On the **Installation** page, go to the **Install Link** section, and select which type of install link you want for your app. For most apps, we recommend the Discord Provided Link. + +The Default Install Settings will appear on the **Installation** page when you have "Discord Provided Link" selected as your install link type. + ## Get Current Application % GET /applications/@me Returns the [application](#DOCS_RESOURCES_APPLICATION/application-object) object associated with the requesting bot user. diff --git a/docs/tutorials/Developing_a_User_Installable_App.mdx b/docs/tutorials/Developing_a_User_Installable_App.mdx index fc7344ba36..80ec10349b 100644 --- a/docs/tutorials/Developing_a_User_Installable_App.mdx +++ b/docs/tutorials/Developing_a_User_Installable_App.mdx @@ -1,8 +1,5 @@ # Developing A User-Installable App -> preview -> User-installed apps are currently in preview and subject to change. Learn details and limitations about the preview in the [change log entry](#DOCS_CHANGE_LOG/userinstallable-apps-preview) - Discord apps can be installed to servers, users, or both. This guide will walk you through building a basic game integration app that is installable to both Discord users and servers. While the tutorial will focus on supporting different [installation contexts](#DOCS_RESOURCES_APPLICATION/installation-context), we'll be building a basic game integration along the way with a wiki lookup with user-specific bookmarking and a server leaderboard. The app has four commands (`/link`, `/profile`, `/leaderboard`, and `/wiki`) that can be run in different installation and interaction contexts (which are concepts we'll dig into later in the tutorial). @@ -104,11 +101,11 @@ The default install settings of your app determines the default [scopes](#DOCS_T ###### Update Install Link -Before adding default install settings, we need to enable Discord provided links. Under the **Install Link** section, select `Discord Provided Link` from the dropdown. Once its selected, the **Default Install Settings** will appear. +Before adding default install settings, we need to select Discord Provided Link for the app's [install link](#DOCS_RESOURCES_APPLICATION/install-links). Under the **Install Link** section, select `Discord Provided Link` from the dropdown if it isn't already selected (it should be by default). Once its selected, the **Default Install Settings** will appear. ###### Adding Default Install Settings -Under the new **Default Install Settings** section: +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`.