Application

Reference for Discord application objects and management endpoints.

Applications (or “apps”) are containers for developer platform features, and can be installed to Discord servers and/or user accounts.

Application object

Application structure

id · snowflake · required

ID of the app

name · string · required

Name of the app

icon · ?string · required

Icon hash of the app

description · string · required

Description of the app

rpc_origins · array of strings

List of RPC origin URLs, if RPC is enabled

bot_public · boolean · required

When false, only the app owner can add the app to guilds

bot_require_code_grant · boolean · required

When true, the app’s bot will only join upon completion of the full OAuth2 code grant flow

bot · partial user object

Partial user object for the bot user associated with the app

terms_of_service_url · string

URL of the app’s Terms of Service

privacy_policy_url · string

URL of the app’s Privacy Policy

owner · partial user object

Partial user object for the owner of the app

verify_key · string · required

Hex encoded key for verification in interactions and the GameSDK’s GetTicket

team · ?team object · required

If the app belongs to a team, this will be a list of the members of that team

guild_id · snowflake

Guild associated with the app. For example, a developer support server.

guild · partial guild object

Partial object of the associated guild

primary_sku_id · snowflake

If this app is a game sold on Discord, this field will be the id of the “Game SKU” that is created, if exists

slug · string

If this app is a game sold on Discord, this field will be the URL slug that links to the store page

cover_image · string

App’s default rich presence invite cover image hash

flags · integer

App’s public flags

approximate_guild_count · integer

Approximate count of guilds the app has been added to

approximate_user_install_count · integer

Approximate count of users that have installed the app (authorized with application.commands as a scope)

approximate_user_authorization_count · integer

Approximate count of users that have OAuth2 authorizations for the app

redirect_uris · array of strings

Array of redirect URIs for the app

interactions_endpoint_url · ?string

Interactions endpoint URL for the app

role_connections_verification_url · ?string

Role connection verification URL for the app

event_webhooks_url · ?string

Event webhooks URL for the app to receive webhook events

event_webhooks_status · application event webhook status

If webhook events are enabled for the app. 1 (default) means disabled, 2 means enabled, and 3 means disabled by Discord

event_webhooks_types · array of strings

List of webhook event types the app subscribes to

tags · array of strings

List of tags describing the content and functionality of the app. Max of 5 tags.

install_params · install params object

Settings for the app’s default in-app authorization link, if enabled

integration_types_config · dictionary

Default scopes and permissions for each supported installation context. Keys are application integration types, values are integration type configuration objects

custom_install_url · string

Default custom authorization URL for the app, if enabled

Example application object

{
  "bot_public": true,
  "bot_require_code_grant": false,
  "cover_image": "31deabb7e45b6c8ecfef77d2f99c81a5",
  "description": "Test",
  "guild_id": "290926798626357260",
  "icon": null,
  "id": "172150183260323840",
  "integration_types_config": {
    "0": {
      "oauth2_install_params": {
        "scopes": ["applications.commands", "bot"],
        "permissions": "2048"
      }
    },
    "1": {
      "oauth2_install_params": {
        "scopes": ["applications.commands"],
        "permissions": "0"
      }
    }
  },
  "name": "Baba O-Riley",
  "interactions_endpoint_url": null,
  "role_connections_verification_url": null,
  "event_webhooks_url": null,
  "event_webhooks_status": 1,
  "owner": {
    "avatar": null,
    "discriminator": "1738",
    "flags": 1024,
    "id": "172150183260323840",
    "username": "i own a bot"
  },
  "primary_sku_id": "172150183260323840",
  "slug": "test",
  "team": {
    "icon": "dd9b7dcfdf5351b9c3de0fe167bacbe1",
    "id": "531992624043786253",
    "members": [
      {
        "membership_state": 2,
        "permissions": ["*"],
        "team_id": "531992624043786253",
        "user": {
          "avatar": "d9e261cd35999608eb7e3de1fae3688b",
          "discriminator": "0001",
          "id": "511972282709709995",
          "username": "Mr Owner"
        }
      }
    ]
  },
  "verify_key": "1e0a356058d627ca38a5c8c9648818061d49e49bd9da9e3ab17d98ad4d6bg2u8"
}

Application integration types

Where an app can be installed, also called its supported installation contexts.

Type	ID	Description
GUILD_INSTALL	0	App is installable to servers
USER_INSTALL	1	App is installable to users

Application integration type configuration object

oauth2_install_params · install params object

Install params for each installation context’s default in-app authorization link

Application event webhook status

Status indicating whether event webhooks are enabled or disabled for an application.

Name	Value	Description
DISABLED	1	Webhook events are disabled by developer
ENABLED	2	Webhook events are enabled by developer
DISABLED_BY_DISCORD	3	Webhook events are disabled by Discord, usually due to inactivity

Application flags

Value	Name	Description
1 << 6	APPLICATION_AUTO_MODERATION_RULE_CREATE_BADGE	Indicates if an app uses the Auto Moderation API
1 << 12	GATEWAY_PRESENCE	Intent required for bots in 100 or more servers to receive presence_update events
1 << 13	GATEWAY_PRESENCE_LIMITED	Intent required for bots in under 100 servers to receive presence_update events, found on the Bot page in your app’s settings
1 << 14	GATEWAY_GUILD_MEMBERS	Intent required for bots in 100 or more servers to receive member-related events like guild_member_add
1 << 15	GATEWAY_GUILD_MEMBERS_LIMITED	Intent required for bots in under 100 servers to receive member-related events, found on the Bot page in your app’s settings
1 << 16	VERIFICATION_PENDING_GUILD_LIMIT	Indicates unusual growth of an app that prevents verification
1 << 17	EMBEDDED	Indicates if an app is embedded within the Discord client (currently unavailable publicly)
1 << 18	GATEWAY_MESSAGE_CONTENT	Intent required for bots in 100 or more servers to receive message content
1 << 19	GATEWAY_MESSAGE_CONTENT_LIMITED	Intent required for bots in under 100 servers to receive message content, found on the Bot page in your app’s settings
1 << 23	APPLICATION_COMMAND_BADGE	Indicates if an app has registered global application commands

Install params object

Install params structure

scopes · array of strings · required

Scopes to add the application to the server with

permissions · string · required

Permissions to request for the bot role

Installation context

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 permission. Server-installed apps are visible to all members of the server, but other factors (like command permissions) determine where and when specific members can interact with the app.

During installation, server-installed apps are authorized with a specific set of OAuth2 scopes and bot user permissions that determine what resources and data the app can access in that server.

User context

Apps installed in a user context (user-installed apps) are visible only to the authorizing user, and therefore don’t require any server-specific permissions.

Apps that support the user installation context are visible across all of an authorizing user’s servers, DMs, and GDMs, but are forced to respect the user’s permissions in the surface where the app is being used.

Setting supported installation contexts

By default, newly-created apps only support installation to guilds.

You can update which installation contexts your app supports in your app’s settings. On the Installation page under the Installation Contexts section, you can select the installation contexts your app supports.

If you update your app to support a new installation context, you will need to update your existing commands if you want them to be supported in the new context.

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.

There are three options when configuring an install link: “Discord Provided Link”, “Custom URL”, and “None”.

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. Discord Provided Links don’t have scopes or bot user permissions defined in the URL. Instead, these links prompt the user for the scopes and bot user permissions configured in your Default Install Settings.

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”. A Custom URL is commonly an OAuth2 /authorize URL that has defined scopes, permissions, and an installation context (integration_type).

---

Get current application

GET /applications/@me

Returns the application object associated with the requesting bot user.

Edit current application

PATCH /applications/@me

Edit properties of the app associated with the requesting bot user. Only properties that are passed will be updated. Returns the updated application object on success.

All parameters to this endpoint are optional.

JSON params

custom_install_url · string

Default custom authorization URL for the app, if enabled

description · string

Description of the app

role_connections_verification_url · string

Role connection verification URL for the app

install_params · install params object

Settings for the app’s default in-app authorization link, if enabled

integration_types_config · dictionary

Default scopes and permissions for each supported installation context

flags · integer

App’s public flags. Only limited intent flags (GATEWAY_PRESENCE_LIMITED, GATEWAY_GUILD_MEMBERS_LIMITED, and GATEWAY_MESSAGE_CONTENT_LIMITED) can be updated via the API.

icon · ?image data

Icon for the app

cover_image · ?image data

Default rich presence invite cover image for the app

interactions_endpoint_url · string

Interactions endpoint URL for the app. Must be valid according to the Receiving an Interaction documentation.

tags · array of strings

List of tags describing the content and functionality of the app (max of 20 characters per tag). Max of 5 tags.

event_webhooks_url · string

Event webhooks URL for the app to receive webhook events

event_webhooks_status · application event webhook status

If webhook events are enabled for the app. 1 to disable, and 2 to enable

event_webhooks_types · array of strings

List of webhook event types to subscribe to

Get application activity instance

GET /applications/{application.id}/activity-instances/{instance_id}

Returns a serialized activity instance, if it exists. Useful for preventing unwanted activity sessions.

Activity instance object

application_id · snowflake · required

Application ID

instance_id · string · required

Activity instance ID

launch_id · snowflake · required

Unique identifier for the launch

location · Activity Location object · required

Location the instance is running in

users · array of snowflakes · required

IDs of the users currently connected to the instance

Activity location object

id · string · required

Unique identifier for the location

kind · Activity Location Kind Enum · required

Enum describing kind of location

channel_id · snowflake · required

ID of the channel

guild_id · ?snowflake

ID of the guild

Activity location kind enum

Enum	Description
gc	Location is a Guild Channel
pc	Location is a Private Channel, such as a DM or GDM

Example activity instance

{
  "application_id": "1215413995645968394",
  "instance_id": "i-1276580072400224306-gc-912952092627435520-912954213460484116",
  "launch_id": "1276580072400224306",
  "location": {
    "id": "gc-912952092627435520-912954213460484116",
    "kind": "gc",
    "channel_id": "912954213460484116",
    "guild_id": "912952092627435520"
  },
  "users": ["205519959982473217"]
}