Embedded App SDK Reference - Discord Developer Platform

The Embedded App SDK handles RPC communication between your application and Discord. It is designed to assist developers in building interactive Activities like games. To learn more about building Activities, see the Building an Activity tutorial or explore the Sample Projects.

Install the SDK

The Embedded App SDK is available via npm and GitHub.

npm install @discord/embedded-app-sdk

After installing, import and instantiate the SDK in your project:

import { DiscordSDK } from "@discord/embedded-app-sdk";

const discordSdk = new DiscordSDK(DISCORD_CLIENT_ID);

SDK Methods

Name	Description
ready	Resolves when your app has successfully connected to the Discord client
subscribe	Subscribe to an Embedded App SDK Event
unsubscribe	Unsubscribe from an Embedded App SDK Event
close	Close the Embedded App

ready()

Resolves when your app has successfully connected to the Discord client. Supported Platforms: Web ✅ iOS ✅ Android ✅ Required Scopes: None Signature: ready(): Promise<void>

async function setup() {
  await discordSdk.ready();
  // Your app logic here
}

Subscribe to a specific event from the list of SDK Events. Supported Platforms: Web ✅ iOS ✅ Android ✅ Required Scopes: Depends on the event. Refer to the Required Scopes for the specific event.

await discordSdk.subscribe("SDK_EVENT_NAME", eventHandler, args);

unsubscribe()

Unsubscribe from an SDK Event your app has already subscribed to. Supported Platforms: Web ✅ iOS ✅ Android ✅ Required Scopes: None

await discordSdk.unsubscribe("SDK_EVENT_NAME");

close()

Close your app with a specified code and reason. Supported Platforms: Web ✅ iOS ✅ Android ✅ Required Scopes: None Signature: close(code: RPCCloseCodes, message: string): void

discordSdk.close(RPCCloseCodes.CLOSE_NORMAL, "You exited from the app");

SDK Commands

These commands let you interact with the Discord client. All commands are prefixed with .commands, e.g. discordSdk.commands.authenticate.

Name	Description
authenticate	Authenticate an existing client with your app
authorize	Authorize a new client with your app
captureLog	Forward logs to your own logger
encourageHardwareAcceleration	Presents a modal to allow enabling hardware acceleration
getChannel	Returns information about a channel by channel ID
getChannelPermissions	Returns permissions for the current user in the connected channel
getEntitlements	Returns a list of entitlements for the current user
getInstanceConnectedParticipants	Returns all participants connected to the instance
getPlatformBehaviors	Returns information about supported platform behaviors
getRelationships	Returns the current user’s relationships (requires Social SDK access)
getSkus	Returns a list of your app’s SKUs
initiateImageUpload	Presents the file upload flow in the Discord client
openExternalLink	Opens an external link from within the Discord client
openInviteDialog	Presents a channel invite modal without requiring additional OAuth scopes
openShareMomentDialog	Presents a modal to share media to a channel or DM
setActivity	Modifies how your Activity’s Rich Presence is displayed
setConfig	Sets whether PIP (picture-in-picture) is interactive
setOrientationLockState	Sets orientation and PIP mode options
shareLink	Presents a modal for the user to share a link to your Activity
startPurchase	Launches the purchase flow for a specific SKU
userSettingsGetLocale	Returns the current user’s locale

authenticate()

Authenticate an existing client with your app. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.authenticate({
  access_token: 'ACCESS_TOKEN_STRING'
});

authorize()

Authorize a new client with your app and request OAuth scopes. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.authorize({
  client_id: DISCORD_CLIENT_ID,
  response_type: "code",
  state: "",
  prompt: "none",
  scope: [
    "identify",
    "guilds",
    "applications.commands",
  ],
});

captureLog()

Forward logs to your own logger. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.captureLog({
  level: 'log',
  message: 'This is my log message!'
});

encourageHardwareAcceleration()

Presents a modal dialog to allow the user to enable hardware acceleration. Supported Platforms: Web ✅ iOS ⛔ Android ⛔ | Required Scopes: None

await discordSdk.commands.encourageHardwareAcceleration();

getChannel()

Returns information about a channel for a provided channel ID. Supported Platforms: Web ✅ iOS ✅ Android ✅ Required Scopes:

guilds for guild channels
guilds + dm_channels.read for GDM channels (dm_channels.read requires Discord approval)

await discordSdk.commands.getChannel({
  channel_id: discordSdk.channelId,
});

getChannelPermissions()

Returns permissions for the current user in the currently connected channel. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: guilds.members.read

await discordSdk.commands.getChannelPermissions();

getEntitlements()

Returns a list of entitlements for the current user. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.getEntitlements();

getInstanceConnectedParticipants()

Returns all participants currently connected to the Activity instance. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.getInstanceConnectedParticipants();

getPlatformBehaviors()

Returns information about supported platform behaviors. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.getPlatformBehaviors();

getRelationships()

Returns the current user’s relationships (friends, pending requests, blocked users). Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: relationships.read

This scope is part of our Social SDK. Submit for access here.

await discordSdk.commands.getRelationships();

getSkus()

Returns a list of SKU objects. SKUs without prices are automatically filtered out. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.getSkus();

initiateImageUpload()

Presents the file upload flow in the Discord client. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.initiateImageUpload();

openExternalLink()

Opens an external link from within the Discord client. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.openExternalLink({
  url: 'https://example.com'
});

openInviteDialog()

Presents a modal with Channel Invite UI without requiring additional OAuth scopes. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

await discordSdk.commands.openInviteDialog();

openShareMomentDialog()

Presents a modal to share media to a channel or direct message. Supported Platforms: Web ✅ iOS ⛔ Android ⛔ | Required Scopes: None

await discordSdk.commands.openShareMomentDialog({
  mediaUrl: 'DISCORD_CDN_URL'
});

setActivity()

Modifies how your Activity’s Rich Presence data is displayed in the Discord client. The inner activity field is a partial Activity object. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: rpc.activities.write

await discordSdk.commands.setActivity({
  activity: {
    type: 0,
    details: 'Details',
    state: 'Playing'
  }
});

Read the Rich Presence with the Embedded App SDK guide for more usage details.

setConfig()

Set whether PIP (picture-in-picture) is interactive. Supported Platforms: Web ✅ iOS ⛔ Android ⛔ | Required Scopes: None

await discordSdk.commands.setConfig({
  use_interactive_pip: true
});

setOrientationLockState()

Locks the application to specific orientations in each of the supported layout modes. Supported Platforms: Web ⛔ iOS ✅ Android ✅ | Required Scopes: None

import {Common} from '@discord/embedded-app-sdk';

await discordSdk.commands.setOrientationLockState({
  lock_state: Common.OrientationLockStateTypeObject.LANDSCAPE,
  picture_in_picture_lock_state: Common.OrientationLockStateTypeObject.LANDSCAPE,
  grid_lock_state: Common.OrientationLockStateTypeObject.UNLOCKED
});

shareLink()

Presents the user with a modal to share a link to your Activity with custom query parameters. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: None

const { success } = await discordSdk.commands.shareLink({
  message: 'This message is shared alongside the link!',
  custom_id: 'some_custom_id',
});
success ? console.log('User shared link!') : console.log('User did not share link!');

startPurchase()

Launches the purchase flow for a specific SKU ID. Supported Platforms: Web ✅ iOS ⛔ Android ⛔ | Required Scopes: None

await discordSdk.commands.startPurchase({sku_id: skuId});

userSettingsGetLocale()

Returns the current user’s locale. Supported Platforms: Web ✅ iOS ✅ Android ✅ | Required Scopes: identify

await discordSdk.commands.userSettingsGetLocale();

SDK Events

Subscribe to these events using the subscribe() method.

Name	Description
READY	Non-subscription event sent immediately after connecting
ERROR	Non-subscription event sent when there is an error
VOICE_STATE_UPDATE	Sent when a user’s voice state changes
SPEAKING_START	Sent when a user in a subscribed voice channel speaks
SPEAKING_STOP	Sent when a user in a subscribed voice channel stops speaking
ACTIVITY_LAYOUT_MODE_UPDATE	Received when a user changes the layout mode
ORIENTATION_UPDATE	Received when screen orientation changes
CURRENT_USER_UPDATE	Received when the current user object changes
CURRENT_GUILD_MEMBER_UPDATE	Received when the current guild member object changes
THERMAL_STATE_UPDATE	Received when device thermal state changes
ACTIVITY_INSTANCE_PARTICIPANTS_UPDATE	Received when the number of instance participants changes
RELATIONSHIP_UPDATE	Received when a relationship of the current user is updated
ENTITLEMENT_CREATE	Received when an entitlement is created for a SKU

READY

Non-subscription event sent immediately after connecting. Contains server information. Required Scopes: None

{
  "v": 1,
  "config": {
    "cdn_host": "cdn.discordapp.com",
    "api_endpoint": "//discord.com/api",
    "environment": "production"
  }
}

ERROR

Non-subscription event sent when there is an error, including command responses. Required Scopes: None

{
  "code": 4006,
  "message": "Not authenticated or invalid scope"
}

VOICE_STATE_UPDATE

Received when a user’s voice state changes (mute, volume, etc.) in a subscribed voice channel. Required Scopes: rpc.voice.read

{
  "voice_state": {
    "mute": false,
    "deaf": false,
    "self_mute": false,
    "self_deaf": false,
    "suppress": false
  },
  "user": {
    "id": "190320984123768832",
    "username": "test 2",
    "discriminator": "7479",
    "avatar": "b004ec1740a63ca06ae2e14c5cee11f3",
    "bot": false
  },
  "nick": "test user 2",
  "volume": 110,
  "mute": false,
  "pan": { "left": 1.0, "right": 1.0 }
}

SPEAKING_START

Received when a user in a subscribed voice channel speaks. Required Scopes: rpc.voice.read

{
  "channel_id": "7173758092142710784",
  "user_id": "7173758143913005056"
}

SPEAKING_STOP

Received when a user in a subscribed voice channel stops speaking. Required Scopes: rpc.voice.read

{
  "channel_id": "7173758211307081728",
  "user_id": "7173758261412237312"
}

ACTIVITY_LAYOUT_MODE_UPDATE

Received when a user changes the layout mode in the Discord client. Required Scopes: None

{ "layout_mode": 1 }

ORIENTATION_UPDATE

Received when screen orientation changes. Required Scopes: None

{ "screen_orientation": 1 }

CURRENT_USER_UPDATE

Received when the current user object changes. Required Scopes: identify

{
  "id": "7173771622812225536",
  "username": "beef_supreme",
  "discriminator": "0",
  "global_name": "Dis Cord",
  "avatar": "abcdefg",
  "bot": false,
  "flags": 1,
  "premium_type": 2
}

CURRENT_GUILD_MEMBER_UPDATE

Received when the current guild member object changes. Required Scopes: identify, guilds.members.read

{
  "user_id": "7173771622812225536",
  "nick": "beef_supreme",
  "guild_id": "613425648685547541",
  "avatar": "abcdefg",
  "color_string": "#ffff00"
}

THERMAL_STATE_UPDATE

Received when Android or iOS thermal states are surfaced to the Discord mobile app. Required Scopes: None

{ "thermal_state": 0 }

ACTIVITY_INSTANCE_PARTICIPANTS_UPDATE

Received when the number of instance participants changes. Required Scopes: None

{
  "participants": [
    {
      "id": "7173771622812225536",
      "username": "beef_supreme",
      "discriminator": "0",
      "global_name": "Dis Cord",
      "avatar": "abcdefg",
      "bot": false,
      "flags": 1,
      "premium_type": 2
    }
  ]
}

RELATIONSHIP_UPDATE

Received when a relationship of the current user is updated. Required Scopes: relationships.read

This scope is part of our Social SDK. Submit for access here.

{
  "type": 1,
  "user": {
    "id": "7173771622812225536",
    "username": "beef_supreme",
    "discriminator": "0",
    "global_name": "Dis Cord",
    "avatar": "abcdefg",
    "bot": false,
    "flags": 1,
    "premium_type": 2
  }
}

ENTITLEMENT_CREATE

Coming soon — not available during Developer Preview.

SDK Interfaces

Activity

Property	Type
name	string
type	number
url?	string \| null
created_at?	number \| null
timestamps?	Timestamp \| null
application_id?	string \| null
details?	string \| null
state?	string \| null
emoji?	Emoji \| null
party?	Party \| null
assets?	Assets \| null
secrets?	Secrets \| null
instance?	boolean \| null
flags?	number \| null

Assets

Property	Type
large_image?	string \| null
large_text?	string \| null
large_url?	string \| null
small_image?	string \| null
small_text?	string \| null
small_url?	string \| null

AuthenticateRequest / AuthenticateResponse

AuthenticateRequest

Property	Type
access_token?	string \| null

AuthenticateResponse

Property	Type
access_token	string
user	User
scopes	string[]
expires	string
application	Application

AuthorizeRequest / AuthorizeResponse

AuthorizeRequest

Property	Type
client_id	string
scope	OAuthScopes[]
response_type?	‘code’
code_challenge?	string
state?	string
prompt?	‘none’
code_challenge_method?	‘S256’

AuthorizeResponse

Property	Type
code	string

User

Property	Type
id	string
username	string
discriminator	string
global_name?	string \| null
avatar?	string \| null
avatar_decoration_data	AvatarDecorationData \| null
bot	boolean
flags?	number \| null
premium_type?	number \| null

GetChannelResponse

Property	Type
id	string
type	ChannelTypesObject
guild_id?	string \| null
name?	string \| null
topic?	string \| null
bitrate?	number \| null
user_limit?	number \| null
position?	number \| null
voice_states	UserVoiceState[]
messages	Message[]

SetActivityRequest

Property	Type
activity	Activity

Timestamp / Party / Secrets

Timestamp

Property	Type
start?	number
end?	number

Party

Property	Type
id?	string \| null
size?	number[] \| null

Secrets

Property	Type
join?	string
match?	string

SDK Enums

RPCCloseCodes

Name	Code
CLOSE_NORMAL	1000
CLOSE_UNSUPPORTED	1003
CLOSE_ABNORMAL	1006
INVALID_CLIENTID	4000
INVALID_ORIGIN	4001
RATELIMITED	4002
TOKEN_REVOKED	4003
INVALID_VERSION	4004
INVALID_ENCODING	4005

OAuthScopes

Value
`'identify'`
`'guilds'`
`'guilds.members.read'`
`'guilds.join'`
`'gdm.join'`
`'rpc'`
`'rpc.activities.write'`
`'rpc.notifications.read'`
`'rpc.voice.write'`
`'rpc.voice.read'`
`'email'`
`'connections'`
`'messages.read'`
`'relationships.read'`
`'activities.read'`
`'activities.write'`
`'dm_channels.read'`
`'bot'`
`'webhook.incoming'`
`'applications.commands'`
`'applications.builds.upload'`
`'applications.builds.read'`
`'applications.store.update'`
`'applications.entitlements'`

ChannelTypesObject

Name	Value
UNHANDLED	-1
DM	1
GROUP_DM	3
GUILD_TEXT	0
GUILD_VOICE	2
GUILD_CATEGORY	4
GUILD_ANNOUNCEMENT	5
ANNOUNCEMENT_THREAD	10
PUBLIC_THREAD	11
PRIVATE_THREAD	12
GUILD_STAGE_VOICE	13
GUILD_DIRECTORY	14
GUILD_FORUM	15

OrientationLockStateTypeObject

Name	Value
UNHANDLED	-1
UNLOCKED	1
PORTRAIT	2
LANDSCAPE	3

LayoutModeTypeObject

Name	Value
UNHANDLED	-1
FOCUSED	0
PIP	1
GRID	2

ThermalStateTypeObject

Name	Value
UNHANDLED	-1
NOMINAL	0
FAIR	1
SERIOUS	2
CRITICAL	3

Relationship Types

Value	Name	Description
0	None	No relationship with the other user
1	Friend	The user is friends with the other user
2	Blocked	The current user has blocked the target user
3	Pending Incoming	Received a friend request, not yet accepted
4	Pending Outgoing	Sent a friend request, not yet accepted
5	Implicit	Documented for visibility; unused in the SDK
6	Suggestion	Documented for visibility; unused in the SDK

SkuTypeObject

Name	Value
UNHANDLED	-1
APPLICATION	1
DLC	2
CONSUMABLE	3
BUNDLE	4
SUBSCRIPTION	5

ConsoleLevel

Value
`'error'`
`'log'`
`'warn'`
`'debug'`
`'info'`

Discord Social SDK

Social SDK Guides

Activities

Platform Features

​Install the SDK

​SDK Methods

​ready()

​subscribe()

​unsubscribe()

​close()

​SDK Commands

​authenticate()

​authorize()

​captureLog()

​encourageHardwareAcceleration()

​getChannel()

​getChannelPermissions()

​getEntitlements()

​getInstanceConnectedParticipants()

​getPlatformBehaviors()

​getRelationships()

​getSkus()

​initiateImageUpload()

​openExternalLink()

​openInviteDialog()

​openShareMomentDialog()

​setActivity()

​setConfig()

​setOrientationLockState()

​shareLink()

​startPurchase()

​userSettingsGetLocale()

​SDK Events

​READY

​ERROR

​VOICE_STATE_UPDATE

​SPEAKING_START

​SPEAKING_STOP

​ACTIVITY_LAYOUT_MODE_UPDATE

​ORIENTATION_UPDATE

​CURRENT_USER_UPDATE

​CURRENT_GUILD_MEMBER_UPDATE

​THERMAL_STATE_UPDATE

​ACTIVITY_INSTANCE_PARTICIPANTS_UPDATE

​RELATIONSHIP_UPDATE

​ENTITLEMENT_CREATE

​SDK Interfaces

​SDK Enums

Install the SDK

SDK Methods

ready()

subscribe()

unsubscribe()

close()

SDK Commands

authenticate()

authorize()

captureLog()

encourageHardwareAcceleration()

getChannel()

getChannelPermissions()

getEntitlements()

getInstanceConnectedParticipants()

getPlatformBehaviors()

getRelationships()

getSkus()

initiateImageUpload()

openExternalLink()

openInviteDialog()

openShareMomentDialog()

setActivity()

setConfig()

setOrientationLockState()

shareLink()

startPurchase()

userSettingsGetLocale()

SDK Events

READY

ERROR

VOICE_STATE_UPDATE

SPEAKING_START

SPEAKING_STOP

ACTIVITY_LAYOUT_MODE_UPDATE

ORIENTATION_UPDATE

CURRENT_USER_UPDATE

CURRENT_GUILD_MEMBER_UPDATE

THERMAL_STATE_UPDATE

ACTIVITY_INSTANCE_PARTICIPANTS_UPDATE

RELATIONSHIP_UPDATE

ENTITLEMENT_CREATE

SDK Interfaces

SDK Enums