Entry Point commands and Interactions updates (#7106)

* updating building an activity guide

* npm run fix:tables

* capitalization and markdown fixes

* fixes

* draft changelog entry

* Adding hiding http response to interactions under a collapse and
encouraging users to use the /callback for feedback on the interaction

* Add new LAUNCH_ACTIVITY callback to interaction callback types

* Adding all of the new response objects from interaction callback and
including the new `with_response` query param for getting a body back
from /callback

* removing alert bubble copy based on internal discussion

* remove package lock changes

* entry point command

* update tables

* Add Setting Up an Entry Point Command dev guide

* make small updates and add asset

* update change log

* update tutorial

* update guide

* update image

* small edits

---------

Co-authored-by: Donald Chen <[email protected]>
Co-authored-by: Mark Lohstroh <[email protected]>

Author: 3 people

docs/activities/Building_An_Activity.mdx

@@ -71,17 +71,17 @@ After you create your app, you'll land on the **General Overview** page of the a
 
 Navigate to `Activities -> Getting Started` in the sidebar.
 
-Review this page and press 'Get Started' to make your app eligible for being embedded.
+Review this page and press **Get Started** to enable Activities for your app.
 
 ![Configure your Activity](activities/getting-started-activities.png)
 
-From the `Activities` section of the developer portal, you can configure:
+From the **Activities** page in your app's settings, you can customize details, settings, and assets related to your Activity. We'll come back to this page later in this guide when we are ready to set up our URL Mappings.
 
-- URL Mappings
-- Settings
-- Art Assets
+#### Entry Point Command
 
-We'll come back to this page later in this guide when we are ready to set up our URL Mappings.
+When you enable Activities for your app, a [default Entry Point command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/default-entry-point-command) called "Launch" is automatically created. This [Entry Point command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-commands) is the primary way for users to launch your Activity in Discord.
+
+By default, interactions with this command will result in Discord opening your Activity for the user and posting a message in the channel where it was launched from. However, if you prefer to handle the interactions in your app, you can update the [`handler` field](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-handlers) or create your own. Additional details are in the Entry Point command [documentation](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-commands) and [development guide](#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/setting-up-an-entry-point-command).
 
 ### Find Your OAuth2 Credentials
 
@@ -447,6 +447,7 @@ async function setupDiscordSdk() {
     scope: [
       "identify",
       "guilds",
+      "applications.commands"
     ],
   });
 
@@ -483,7 +484,7 @@ document.querySelector('#app').innerHTML = `
 `;
 ```
 
-Now if we relaunch our app, we'll be prompted to authorize with Discord using the `identify` and `guilds` scopes.
+Now if we relaunch our app, we'll be prompted to authorize with Discord using the `identify`, `guilds`, and `applications.commands` scopes.
 
 ![Prompt to authorize Activity](activities/tutorial-auth.png)
 

docs/activities/Development_Guides.mdx

@@ -32,6 +32,9 @@ These guides include suggested development practices, SDK commands, and user flo
   <Card title="Open Share Moment Dialog" link="#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/open-share-moment-dialog">
     Open a dialog to share media from your application to a channel, DM, or GDM.
   </Card>
+  <Card title="Setting Up an Entry Point Command" link="#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/setting-up-an-entry-point-command">
+    Configure a command that allows users to open your Activity from the App Launcher.
+  </Card>
   <Card title="Encourage Hardware Acceleration" link="#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/encourage-hardware-acceleration">
     Open a dialog to enable hardware acceleration for compute-intensive applications.
   </Card>
@@ -416,6 +419,47 @@ User Experience
 
 ![share-moment-dialog](activities/share-moment-dialog-example.png)
 
+---
+
+### Setting Up an Entry Point Command
+
+An [Entry Point command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-commands) is required for users to be able to launch your Activity from the [App Launcher menu](https://support.discord.com/hc/articles/21334461140375-Using-Apps-on-Discord#h_01HRQSA6C8TRHS722P1H3HW1TV) in Discord.
+
+When you enable Activities in your [app's settings](http://discord.com/developers/applications), a [default Entry Point command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/default-entry-point-command) is automatically created for your app. The default Entry Point command will use the `DISCORD_LAUNCH_ACTIVITY` (`2`) [handler type](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-entry-point-command-handler-types), which means that Discord automatically launches your Activity for the user and posts a follow-up message into the channel where it was launched from.
+
+If you want to handle sending messages yourself, you can update the handler to be `APP_HANDLER` (`1`). Details about Entry Point command handlers is in the [Entry Point command documentation](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-handlers).
+
+#### Customizing the Default Entry Point Command
+
+Entry Point commands can be customized in the same way as other [commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS). Since Entry Point commands can only be [global](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/making-a-global-command), you'll use the HTTP endpoints for global  commands:
+- **Edit your existing Entry Point command's name or details** using the [Edit Global Application Command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/edit-global-application-command) endpoint. If you don't know the ID for your app's Entry Point command, use the [Get Global Application Commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/get-global-application-commands) endpoint to retrieve it.
+- **Make a different (option-less) command your Entry Point command** by updating its [command `type`](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types) to `PRIMARY_ENTRY_POINT` (type `4`). Your app can only have one Entry Point command, so if your app already has one, you must first [delete](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/delete-global-application-command) it or [update](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/edit-global-application-command) its [command `type`](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types).
+
+#### Creating an Entry Point Command
+
+To create a new Entry Point command, you can call the [Create Global Application Command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/create-global-application-command) endpoint and set the [command `type`](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types) to `PRIMARY_ENTRY_POINT` (type `4`).
+
+Your command payload may look something like this:
+
+```json
+{
+  "name": "launch",
+  "description": "Launch Realms of Wumpus",
+  // PRIMARY_ENTRY_POINT is type 4
+  "type": 4,
+  // DISCORD_LAUNCH_ACTIVITY is handler value 2
+  "handler": 2,
+  // integration_types and contexts define where your command can be used (see below)
+  "integration_types": [0, 1],
+  "contexts": [0, 1, 2]
+}
+```
+
+In addition to the `type` and `handler` values, the command payload includes `integration_types` and `contexts` which let you configure when and where your command can be used:
+- `integration_types` defines the [installation contexts](#DOCS_RESOURCES_APPLICATION/installation-context) where your command is available (to a server, to a user's account, or both). If you don't set `integration_types` when creating a command, it will default to your app's [currently-supported installation contexts](#DOCS_RESOURCES_APPLICATION/setting-supported-installation-contexts).
+- `contexts` defines the [interaction contexts](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-context-types) where a command can be run in Discord (in a server, in a DM with your app, and/or in DMs and Group DMs with other users).
+
+Details about both of these fields are in the [command contexts](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/contexts) documentation.
 
 ---
 

docs/change_log/2024-08-26-entry-point-commands.md

@@ -0,0 +1,19 @@
+---
+title: "Entry Point Commands"
+date: "2024-08-26"
+topics:
+- "Activities"
+- "Interactions"
+---
+
+Apps with [Activities](#DOCS_ACTIVITIES_OVERVIEW) enabled can now create [Entry Point commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-commands) using the `PRIMARY_ENTRY_POINT` (type `4`) [command type](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-types). Apps are limited to one globally-scoped Entry Point command, which appears in the App Launcher.
+
+When creating or updating an Entry Point command, an [Entry Point handler](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-entry-point-command-handler-types) can be defined using the [`handler` field](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-object-application-command-structure). The `handler` field determines whether your app wants to manually handle responding to the interaction:
+- If the value is `DISCORD_LAUNCH_ACTIVITY` (`2`), Discord will automatically handle the interaction and send a follow-up message to the channel where the Entry Point command was invoked from.
+- If the value is `APP_HANDLER` (`1`), your app will receive an interaction token and will be responsible for responding to the interaction. In this case, you can launch your Activity using the `LAUNCH_ACTIVITY` (type `12`) [interaction callback](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-response-object-interaction-callback-type).
+
+More details about Entry Point commands can be found in the [Application Commands documentation](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/entry-point-commands) and in the [Activity development guide](#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/setting-up-an-entry-point-command).
+
+### Default Entry Point Commands
+
+Starting today, when you enable Activities in your [app's settings](http://discord.com/developers/applications), a [default Entry Point command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/default-entry-point-command) called "Launch" will automatically be created for your app. This can be customized or deleted like other commands if you want to update the name or handler type.

docs/change_log/2024-08-26-launching-activities-via-interactions.md

@@ -0,0 +1,9 @@
+---
+title: "Launching Activities in Response to Interactions"
+date: "2024-08-26"
+topics:
+- "Activities"
+- "Interactions"
+---
+
+[Activities](#DOCS_ACTIVITIES_OVERVIEW) can now be launched as a response to interactions using the `LAUNCH_ACTIVITY` (type `12`) [interaction callback type](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-response-object-interaction-callback-type). `LAUNCH_ACTIVITY` can be used in response to `APPLICATION_COMMAND`, `MESSAGE_COMPONENT`, and `MODAL_SUBMIT` [interaction types](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-type).