Embedded App SDK Reference

The Embedded App SDK handles making RPC calls between your application and Discord. It is designed to assist developers in developing interactive Activities like games.

To learn more about building Activities, check out our Building an Activity tutorial or explore our Sample Projects.

The Embedded App SDK is available via npm and GitHub.

In your frontend JavaScript project directory, install using your package manager of choice.

npm install @discord/embedded-app-sdk

After installing, you can import and instantiate the SDK in your project.

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

const discordSdk = new DiscordSDK(DISCORD_CLIENT_ID);

Resolves when your app has successfully connected to the Discord client.

No scopes required

ready(): Promise<void>

async function setup() {
  await discordSdk.ready();
  // The rest of your app logic
}

Used to subscribe to a specific event from the list of SDK Events.

Depends on the event. Refer to the Required Scopes for the specific event you are subscribing to.

subscribe<Event>(event: Event, listener: (data: EventPayloadData<Event>) => void, ...subscribeArgs: Partial<EventPayloadData<Event>>): Promise<EventEmitter>

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

Used to unsubscribe to SDK Events that your app has already subscribed to.

No scopes required

The EventPayloadData will vary based on the event you are unsubscribing from. See the specific event for details.

unsubscribe<Event>(event: Event, listener: (data: EventPayloadData<Event>) => void, ...subscribeArgs: Partial<EventPayloadData<Event>>): Promise<EventEmitter>

await discordSdk.unsubscribe("SDK_EVENT_NAME");

Used to close your app with a specified code and reason.

No scopes required

close(code: RPCCloseCodes, message: string): void

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

Developers can use these commands to interact with the Discord client. The following SDK commands are prefixed with .commands, such as, discordSDK.commands.authenticate.

Authenticate an existing client with your app.

No scopes required

authenticate(args: AuthenticateRequest): Promise<AuthenticateResponse>

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

Authorize a new client with your app.

No scopes required

authorize(args: AuthorizeRequest): Promise<AuthorizeResponse>

await discordSdk.commands.authorize({
  client_id: DISCORD_CLIENT_ID,
  response_type: "code",
  state: "",
  prompt: "none",
  scope: [
    // "applications.builds.upload",
    // "applications.builds.read",
    // "applications.store.update",
    // "applications.entitlements",
    // "bot",
    "identify",
    // "connections",
    // "email",
    // "gdm.join",
    "guilds",
    // "guilds.join",
    // "guilds.members.read",
    // "messages.read",
    // "relationships.read",
    // 'rpc.activities.write',
    // "rpc.notifications.read",
    // "rpc.voice.write",
    // "rpc.voice.read",
    // "webhook.incoming",
  ],
});

Forward logs to your own logger.

No scopes required

captureLog(args: CaptureLogRequest): Promise<void>

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

Presents a modal dialog to allow enabling of hardware acceleration.

No scopes required

encourageHardwareAcceleration(): Promise<EncourageHardwareAccelerationResponse>

await discordSdk.commands.encourageHardwareAcceleration();

Returns information about the channel for a provided channel ID.

• [guilds] for guild channels
• [guilds, dm_channels.read] for GDM channels. dm_channels.read requires approval from Discord.

getChannel(args: GetChannelRequest): Promise<GetChannelResponse>

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

Returns permissions for the current user in the currently connected channel.

• guilds.members.read

getChannelPermissions(): Promise<GetChannelPermissionsResponse>

await discordSdk.commands.getChannelPermissions();

Returns a list of entitlements for the current user.

No scopes required

getEntitlements(): Promise<GetEntitlementsResponse>

await discordSdk.commands.getEntitlements();

Returns all participants connected to the instance.

No scopes required

getInstanceConnectedParticipants(): Promise<GetInstanceConnectedParticipantsResponse>

await discordSdk.commands.getInstanceConnectedParticipants();

Returns information about supported platform behaviors.

No scopes required

getPlatformBehaviors(): Promise<GetPlatformBehaviorsResponse>

await discordSdk.commands.getPlatformBehaviors();

Returns the current user's relationships.

• relationships.read

getRelationships(): Promise<GetRelationshipsResponse>

await discordSdk.commands.getRelationships();

Returns a list of SKU objects. SKUs without prices are automatically filtered out.

No scopes required

getSkus(): Promise<GetSkusResponse>

await discordSdk.commands.getSkus();

Presents the file upload flow in the Discord client.

No scopes required

initiateImageUpload(): Promise<InitiateImageUploadResponse>

await discordSdk.commands.initiateImageUpload();

Allows for opening an external link from within the Discord client.

No scopes required

openExternalLink(args: OpenExternalLinkRequest): Promise<OpenExternalLinkResponse>

await discordSdk.commands.openExternalLink({
  url: 'string url'
});

Presents a modal dialog with Channel Invite UI without requiring additional OAuth scopes.

No scopes required

openInviteDialog(): Promise<void>

await discordSdk.commands.openInviteDialog();

Presents a modal dialog to share media to a channel or direct message.

No scopes required

openShareMomentDialog(args: OpenShareMomentDialogRequest) Promise<void>

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

Modifies how your Activity's Rich Presence data is displayed in the Discord client. The inner activity field is a partial Activity object.

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

• rpc.activities.write

setActivity(args: SetActivityRequest): Promise<Activity>

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

Set whether or not the PIP (picture-in-picture) is interactive.

No scopes required

setConfig(args: SetConfigRequest): Promise<SetConfigResponse>

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

Locks the application to specific orientations in each of the supported layout modes.

No scopes required

setOrientationLockState(args: SetOrientationLockStateRequest): Promise<void>

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
});

Presents the user with a modal to share a link

No scopes required

shareLink(args: ShareLinkRequest): Promise<ShareLinkResponse><void>

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!');

Launches the purchase flow for a specific SKU ID.

No scopes required

startPurchase(args: StartPurchaseRequest): Promise<StartPurchaseResponse>

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

Returns the current user's locale.

• identify

userSettingsGetLocale(): Promise<UserSettingsGetLocaleResponse>

await discordSdk.commands.userSettingsGetLocale();

Developers may use the following events alongside the subscribe() SDK method to subscribe to events from Discord and supported devices.

Non-subscription event sent immediately after connecting, contains server information.

No scopes required

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

Non-subscription event sent when there is an error, including command responses.

No scopes required

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

Received when a user's voice state changes in a subscribed voice channel (mute, volume, etc).

• 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
  }
}

Received when a user in a subscribed voice channel speaks.

• rpc.voice.read

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

Received when a user in a subscribed voice channel stops speaking.

• rpc.voice.read

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

Received when a user changes the layout mode in the Discord client.

No scopes required

{
  "layout_mode": 1
}

Received when screen orientation changes.

No scopes required

{
  "screen_orientation": 1
}

Received when the current user object changes.

• identify

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

Received when the current guild member object changes.

• identify
• guilds.members.read

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

Received when Android or iOS thermal states are surfaced to the Discord mobile app.

No scopes required

{
  thermal_state: 0
}

Received when the number of instance participants changes.

No scopes required

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

Received when a relationship of the current user is updated.

• relationships.read

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