RPC

RPC over IPC

Discord's RPC server supports IPC (Inter-Process Communication) as transport for native applications and games. This allows high-performance, local communication with the Discord client without requiring network-level overhead.

IPC Path

Platform	Path Format
Windows	`\\?\pipe\discord-ipc-{n}`
Linux/macOS	`${XDG_RUNTIME_DIR}/discord-ipc-{n}`, `${TMPDIR}/discord-ipc-{n}`, `${TMP}/discord-ipc-{n}`, `${TEMP}/discord-ipc-{n}`, or `/tmp/discord-ipc-{n}`

On Linux/macOS, Discord resolves the IPC prefix in this order: XDG_RUNTIME_DIR, TMPDIR, TMP, TEMP, then /tmp as a final fallback.

Connecting to IPC

To begin a session, the application must open the IPC socket and send a HANDSHAKE opcode.

Handshake Payload

The payload is a JSON object containing the RPC version and your application's client ID.

Field	Type	Description
`v`	`integer`	RPC version
`client_id`	`string`	Your application's client ID

Example Handshake

[00 00 00 00] // Opcode 0 (Handshake)
[2D 00 00 00] // Length 45
{"v":1,"client_id":"123456789012345678"}

Upon success, Discord will respond with a FRAME (Opcode 1) containing the READY event.

Once the handshake is complete, all subsequent requests and responses use the FRAME opcode. The internal structure of these frames follows the standard RPC Payload structure

Opcodes

Opcode	Name	Description
`0`	`HANDSHAKE`	Sent by the client to initiate the connection
`1`	`FRAME`	Used for all standard RPC commands and events
`2`	`CLOSE`	Sent by either side to close the connection
`3`	`PING`	Sent to check if the connection is alive
`4`	`PONG`	Response to a `PING`

RPC over WebSocket (Deprecated)

All Discord clients have an RPC server running on localhost that allows control over local Discord clients.

Connecting to WebSocket

The local RPC server runs on localhost (127.0.0.1) and is set up to process WebSocket connections and proxy API requests.

For WebSocket connections, the connection is always ws://127.0.0.1:PORT/?v=VERSION&client_id=CLIENT_ID&encoding=ENCODING:

CLIENT_ID is the client ID of the application accessing the RPC Server.
VERSION is the version of the RPC Server.
PORT is the port of the RPC Server.
ENCODING is the type of encoding for this connection to use. json and etf are supported.

To begin, you'll need to create an app. Head to your apps and click the big plus button. When you create an app on our Developers site, you must specify an "RPC Origin" and "Redirect URI" from which to permit connections and authorizations. The origin you send when connecting and the redirect uri you send when exchanging an authorization code for an access token must match one of the ones entered on the Developers site.

When establishing a WebSocket connection, we verify the Origin header on connection to prevent client ID spoofing. You will be instantly disconnected if the Origin does not match.

If you're connecting to the RPC server from within a browser, RPC origins are usually in the form SCHEME://HOST[:PORT], where SCHEME is typically https or http, HOST is your domain or ip, and PORT is the port of the webserver from which the user will be connecting (omitted for ports 80 and 443). For example, https://discord.com would be used if the user were connecting from https://discord.com/some/page/url.

If you're connecting to the RPC server from within a non-browser application (like a game), you just need to make sure that the origin is sent with the upgrade request when connecting to the WebSocket. For local testing, we recommend testing with an origin like https://localhost. For production apps, we recommend setting the origin to your company/game's domain, for example https://discord.com.

RPC Server Ports

The port range for Discord's local RPC server is [6463, 6472]. Since the RPC server runs locally, there's a chance it might not be able to obtain its preferred port when it tries to bind to one. For this reason, the local RPC server will pick one port out of a range of these 10 ports, trying sequentially until it can bind to one. When implementing your client, you should perform the same sequential checking to find the correct port to connect to.

RPC Versions

Version	Out of Service
1	no

Restrictions

For connections to the RPC server, a list of approved testers is used to restrict access while you're still developing. You can invite up to 50 people.

For applications/games not approved, we limit you to creating 10 guilds and 10 channels. This limit is raised to virtually unlimited after approval.

Payloads

Payload Structure

Field	Type	Description	Present
cmd	enum	payload command	Always
nonce	string	unique string used once for replies from the server	In responses to commands (not subscribed events)
evt	enum	subscription event	In subscribed events, errors, and (un)subscribing events
data	object	event data	In responses from the server
args	object	command arguments	In commands sent to the server

Authenticating

In order to call any commands over RPC, you must be authenticated or you will receive a code 4006 error response. To begin, call AUTHORIZE:

RPC Authorize Example

JSON

{
  "nonce": "f48f6176-4afb-4c03-b1b8-d960861f5216",
  "args": {
    "client_id": "192741864418312192",
    "scopes": ["rpc", "identify"]
  },
  "cmd": "AUTHORIZE"
}

The user will then be prompted to authorize your app to access RPC on Discord. The AUTHORIZE command returns a code that you can exchange with a POST to https://discord.com/api/oauth2/token containing the standard OAuth2 body parameters for the token exchange. The token endpoint on our API will return an access_token that can be sent with AUTHENTICATE:

RPC Authenticate Example

JSON

{
  "nonce": "5bb10a43-1fdc-4391-9512-0c8f4aa203d4",
  "args": {
    "access_token": "CZhtkLDpNYXgPH9Ml6shqh2OwykChw"
  },
  "cmd": "AUTHENTICATE"
}

You can now call RPC commands on behalf of the authorized user!

Commands and Events

Commands are requests made to the RPC socket by a client.

RPC Commands

Name	Description
DISPATCH	event dispatch
AUTHORIZE	used to authorize a new client with your app
AUTHENTICATE	used to authenticate an existing client with your app
GET_GUILD	used to retrieve guild information from the client
GET_GUILDS	used to retrieve a list of guilds from the client
GET_CHANNEL	used to retrieve channel information from the client
GET_CHANNELS	used to retrieve a list of channels for a guild from the client
SUBSCRIBE	used to subscribe to an RPC event
UNSUBSCRIBE	used to unsubscribe from an RPC event
SET_USER_VOICE_SETTINGS	used to change voice settings of users in voice channels
SELECT_VOICE_CHANNEL	used to join or leave a voice channel, group dm, or dm
GET_SELECTED_VOICE_CHANNEL	used to get the current voice channel the client is in
SELECT_TEXT_CHANNEL	used to join or leave a text channel, group dm, or dm
GET_VOICE_SETTINGS	used to retrieve the client's voice settings
SET_VOICE_SETTINGS	used to set the client's voice settings
SET_CERTIFIED_DEVICES	used to send info about certified hardware devices
SET_ACTIVITY	used to update a user's Rich Presence
SEND_ACTIVITY_JOIN_INVITE	used to consent to a Rich Presence Ask to Join request
CLOSE_ACTIVITY_REQUEST	used to reject a Rich Presence Ask to Join request

Events are payloads sent over the socket to a client that correspond to events in Discord.

RPC Events

Name	Description
READY	non-subscription event sent immediately after connecting, contains server information
ERROR	non-subscription event sent when there is an error, including command responses
CURRENT_USER_UPDATE	sent when the local user's data (avatar, username, etc.) changes
RELATIONSHIP_UPDATE	sent when a relationship (friend, block, etc.) is added or removed
GUILD_STATUS	sent when a subscribed server's state changes
GUILD_CREATE	sent when a guild is created/joined on the client
CHANNEL_CREATE	sent when a channel is created/joined on the client
VOICE_CHANNEL_SELECT	sent when the client joins a voice channel
VOICE_STATE_CREATE	sent when a user joins a subscribed voice channel
VOICE_STATE_UPDATE	sent when a user's voice state changes in a subscribed voice channel (mute, volume, etc.)
VOICE_STATE_DELETE	sent when a user parts a subscribed voice channel
VOICE_SETTINGS_UPDATE	sent when the client's voice settings update
VOICE_CONNECTION_STATUS	sent when the client's voice connection status 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
MESSAGE_CREATE	sent when a message is created in a subscribed text channel
MESSAGE_UPDATE	sent when a message is updated in a subscribed text channel
MESSAGE_DELETE	sent when a message is deleted in a subscribed text channel
NOTIFICATION_CREATE	sent when the client receives a notification (mention or new message in eligible channels)
ACTIVITY_JOIN	sent when the user clicks a Rich Presence join invite in chat to join a game
ACTIVITY_SPECTATE	sent when the user clicks a Rich Presence spectate invite in chat to spectate a game
ACTIVITY_JOIN_REQUEST	sent when the user receives a Rich Presence Ask to Join request
ACTIVITY_INVITE	sent when the user receives an activity invitation
ENTITLEMENT_CREATE	sent when a user purchases or receives a new entitlement (SKU/Game)
ENTITLEMENT_DELETE	sent when an entitlement is removed

AUTHORIZE

Used to authenticate a new client with your app. By default this pops up a modal in-app that asks the user to authorize access to your app.

We currently do not allow access to RPC for unapproved apps without being on the game's list of testers. We grant 50 testing spots, which should be ample for development. After approval, this restriction is removed and your app will be accessible to anyone.

We also have an RPC token system to bypass the user authorization modal. This is usable by approved games as well as by users on a game's list of testers, and also disallows use of the messages.read scope. If you have been granted access, you can send a POST request to https://discord.com/api/oauth2/token/rpc with your application's client_id and client_secret in the body (sent as a url-encoded body, not JSON). You can then pass the returned rpc_token value to the rpc_token field in your RPC authorize request (documented below).

Authorize Argument Structure

Field	Type	Description
scopes	array of OAuth2 scopes	scopes to authorize
client_id	string	OAuth2 application id
rpc_token	string	one-time use RPC token
username	string	username to create a guest account with if the user does not have Discord

Authorize Response Structure

Field	Type	Description
code	string	OAuth2 authorization code

Example Authorize Command Payload

JSON

{
  "nonce": "f48f6176-4afb-4c03-b1b8-d960861f5216",
  "args": {
    "client_id": "192741864418312192",
    "scopes": ["rpc", "identify"]
  },
  "cmd": "AUTHORIZE"
}

Example Authorize Response Payload

JSON

{
  "cmd": "AUTHORIZE",
  "data": {
    "code": "O62Q9JzFe8BEOUzIfsAndOjNd2V4sJ"
  },
  "nonce": "f48f6176-4afb-4c03-b1b8-d960861f5216"
}

AUTHENTICATE

Used to authenticate an existing client with your app.

Authenticate Argument Structure

Field	Type	Description
access_token	string	OAuth2 access token

Authenticate Response Structure

Field	Type	Description
user	partial user object	the authed user
scopes	array of OAuth2 scopes	authorized scopes
expires	date	expiration date of OAuth2 token
application	OAuth2 application object	application the user authorized

OAuth2 Application Structure

Field	Type	Description
description	string	application description
icon	string	hash of the icon
id	snowflake	application client id
rpc_origins	array of strings	array of rpc origin urls
name	string	application name

Example Authenticate Command Payload

JSON

{
  "nonce": "5bb10a43-1fdc-4391-9512-0c8f4aa203d4",
  "args": {
    "access_token": "CZhtkLDpNYXgPH9Ml6shqh2OwykChw"
  },
  "cmd": "AUTHENTICATE"
}

Example Authenticate Response Payload

JSON

{
  "cmd": "AUTHENTICATE",
  "data": {
    "application": {
      "description": "test app description",
      "icon": "d6b51c21c48482d5b64aa4832d92fe14",
      "id": "192741864418312192",
      "rpc_origins": ["http://localhost:3344"],
      "name": "test app"
    },
    "expires": "2017-06-29T19:09:52.361000+00:00",
    "user": {
      "username": "test user",
      "discriminator": "7479",
      "id": "190320984123768832",
      "avatar": "b004ec1740a63ca06ae2e14c5cee11f3"
    },
    "scopes": ["rpc", "identify"]
  },
  "nonce": "5bb10a43-1fdc-4391-9512-0c8f4aa203d4"
}

GET_GUILDS

Used to get a list of guilds the client is in.

Get Guilds Response Structure

Field	Type	Description
guilds	array of partial guild objects	the guilds the user is in

Example Get Guilds Command Payload

JSON

{
  "nonce": "e16fcbed-8bfa-4fd4-ba09-73b72e809833",
  "args": {},
  "cmd": "GET_GUILDS"
}

Example Get Guilds Response Payload

JSON

{
  "cmd": "GET_GUILDS",
  "data": {
    "guilds": [
      {
        "id": "199737254929760256",
        "name": "test"
      }
    ]
  },
  "nonce": "e16fcbed-8bfa-4fd4-ba09-73b72e809833"
}

GET_GUILD

Used to get a guild the client is in.

Get Guild Argument Structure

Field	Type	Description
guild_id	string	id of the guild to get
timeout	integer	asynchronously get guild with time to wait before timing out

Get Guild Response Structure

Field	Type	Description
id	string	guild id
name	string	guild name
icon_url	string	guild icon url
members	array of guild member objects	members of the guild (deprecated; always empty array)

Example Get Guild Command Payload

JSON

{
  "nonce": "9524922c-3d32-413a-bdaa-0804f4332588",
  "args": {
    "guild_id": "199737254929760256"
  },
  "cmd": "GET_GUILD"
}

Example Get Guild Response Payload

JSON

{
  "cmd": "GET_GUILD",
  "data": {
    "id": "199737254929760256",
    "name": "test",
    "icon_url": null,
    "members": []
  },
  "nonce": "9524922c-3d32-413a-bdaa-0804f4332588"
}

GET_CHANNEL

Used to get a channel the client is in.

Get Channel Argument Structure

Field	Type	Description
channel_id	string	id of the channel to get

Get Channel Response Structure

Field	Type	Description
id	string	channel id
guild_id	string	channel's guild id
name	string	channel name
type	integer	channel type (guild text: 0, guild voice: 2, dm: 1, group dm: 3)
topic	string	(text) channel topic
bitrate	integer	(voice) bitrate of voice channel
user_limit	integer	(voice) user limit of voice channel (0 for none)
position	integer	position of channel in channel list
voice_states	array of voice state objects	(voice) channel's voice states
messages	array of message objects	(text) channel's messages

Example Get Channel Command Payload

JSON

{
  "nonce": "f682697e-d257-4a17-ac0a-7e4b84e66663",
  "args": {
    "channel_id": "199737254929760257"
  },
  "cmd": "GET_CHANNEL"
}

Example Get Channel Response Payload

JSON

{
  "cmd": "GET_CHANNEL",
  "data": {
    "id": "199737254929760257",
    "name": "General",
    "type": 2,
    "bitrate": 64000,
    "user_limit": 0,
    "guild_id": "199737254929760256",
    "position": 0,
    "voice_states": [
      {
        "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
        }
      }
    ]
  },
  "nonce": "f682697e-d257-4a17-ac0a-7e4b84e66663"
}

GET_CHANNELS

Used to get a guild's channels the client is in.

Get Channels Argument Structure

Field	Type	Description
guild_id	string	id of the guild to get channels for

Get Channels Response Structure

Field	Type	Description
channels	array of partial channel objects	guild channels the user is in

Example Get Channels Command Payload

JSON

{
  "nonce": "0dee7bd4-8f62-4ecc-9e0f-1b1839a4fa93",
  "args": {
    "guild_id": "199737254929760256"
  },
  "cmd": "GET_CHANNELS"
}

Example Get Channels Response Payload

JSON

{
  "cmd": "GET_CHANNELS",
  "data": {
    "channels": [
      {
        "id": "199737254929760256",
        "name": "general",
        "type": 0
      },
      {
        "id": "199737254929760257",
        "name": "General",
        "type": 2
      }
    ]
  },
  "nonce": "0dee7bd4-8f62-4ecc-9e0f-1b1839a4fa93"
}

SET_USER_VOICE_SETTINGS

Used to change voice settings of users in voice channels

Set User Voice Settings Argument and Response Structure

Field	Type	Description
user_id	string	user id
pan?	pan object	set the pan of the user
volume?	integer	set the volume of user (defaults to 100, min 0, max 200)
mute?	boolean	set the mute state of the user

Pan Object

Field	Type	Description
left	float	left pan of user (min: 0.0, max: 1.0)
right	float	right pan of user (min: 0.0, max: 1.0)

Example Set User Voice Settings Command Payload

JSON

{
  "nonce": "eafc8152-2248-4478-9827-8457b7900cb4",
  "args": {
    "user_id": "192731515703001088",
    "pan": {
      "left": 1.0,
      "right": 1.0
    },
    "volume": 120,
    "mute": false
  },
  "cmd": "SET_USER_VOICE_SETTINGS"
}

Example Set User Voice Settings Response Payload

JSON

{
  "cmd": "SET_USER_VOICE_SETTINGS",
  "data": {
    "user_id": "192731515703001088",
    "pan": {
      "left": 1.0,
      "right": 1.0
    },
    "volume": 120,
    "mute": false
  },
  "nonce": "eafc8152-2248-4478-9827-8457b7900cb4"
}

SELECT_VOICE_CHANNEL

Used to join and leave voice channels, group dms, or dms. Returns the Get Channel response, null if none.

Select Voice Channel Argument Structure

Field	Type	Description
channel_id	string	channel id to join (or `null` to leave)
timeout	integer	asynchronously join channel with time to wait before timing out
force	boolean	forces a user to join a voice channel
navigate	boolean	after joining the voice channel, navigate to it in the client

Example Select Voice Channel Command Payload

JSON

{
  "nonce": "5d9df76d-6408-46a1-9368-33dca74fa423",
  "args": {
    "channel_id": "199737254929760257"
  },
  "cmd": "SELECT_VOICE_CHANNEL"
}

Example Select Voice Channel Response Payload

JSON

{
  "cmd": "SELECT_VOICE_CHANNEL",
  "data": {
    "id": "199737254929760257",
    "name": "General",
    "type": 2,
    "bitrate": 64000,
    "user_limit": 0,
    "guild_id": "199737254929760256",
    "position": 0,
    "voice_states": [
      {
        "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",
        "mute": false,
        "volume": 110,
        "pan": {
          "left": 1.0,
          "right": 1.0
        }
      }
    ]
  },
  "nonce": "5d9df76d-6408-46a1-9368-33dca74fa423"
}

GET_SELECTED_VOICE_CHANNEL

Used to get the client's current voice channel. There are no arguments for this command. Returns the Get Channel response, or null if none.

SELECT_TEXT_CHANNEL

Used to join and leave text channels, group dms, or dms. Returns the Get Channel response, or null if none.

Select Text Channel Argument Structure

Field	Type	Description
channel_id	string	channel id to join (or `null` to leave)
timeout	integer	asynchronously join channel with time to wait before timing out

GET_VOICE_SETTINGS

Get Voice Settings Response Structure

Field	Type	Description
input	voice settings input object	input settings
output	voice settings output object	output settings
mode	voice settings mode object	voice mode settings
automatic_gain_control	boolean	state of automatic gain control
echo_cancellation	boolean	state of echo cancellation
noise_suppression	boolean	state of noise suppression
qos	boolean	state of voice quality of service
silence_warning	boolean	state of silence warning notice
deaf	boolean	state of self-deafen
mute	boolean	state of self-mute

Voice Settings Input Object

Field	Type	Description
device_id	string	device id
volume	float	input voice level (min: 0, max: 100)
available_devices	array of objects	array of read-only device objects containing `id` and `name` string keys

Voice Settings Output Object

Field	Type	Description
device_id	string	device id
volume	float	output voice level (min: 0, max: 200)
available_devices	array of objects	array of read-only device objects containing `id` and `name` string keys

Voice Settings Mode Object

Field	Type	Description
type	string	voice setting mode type (can be `PUSH_TO_TALK` or `VOICE_ACTIVITY`)
auto_threshold	boolean	voice activity threshold automatically sets its threshold
threshold	float	threshold for voice activity (in dB) (min: -100, max: 0)
shortcut	shortcut key combo object	shortcut key combos for PTT
delay	float	the PTT release delay (in ms) (min: 0, max: 2000)

Shortcut Key Combo Object

Field	Type	Description
type	integer	see key types
code	integer	key code
name	string	key name

Key Types

Type	Id
KEYBOARD_KEY	0
MOUSE_BUTTON	1
KEYBOARD_MODIFIER_KEY	2
GAMEPAD_BUTTON	3

Example Get Voice Settings Response Payload

JSON

{
  "cmd": "GET_VOICE_SETTINGS",
  "data": {
    "input": {
      "available_devices": [
        {
          "id": "default",
          "name": "Default"
        },
        {
          "id": "Built-in Microphone",
          "name": "Built-in Microphone"
        }
      ],
      "device_id": "default",
      "volume": 49.803921580314636
    },
    "output": {
      "available_devices": [
        {
          "id": "default",
          "name": "Default"
        },
        {
          "id": "Built-in Output",
          "name": "Built-in Output"
        }
      ],
      "device_id": "default",
      "volume": 93.00000071525574
    },
    "mode": {
      "type": "VOICE_ACTIVITY",
      "auto_threshold": true,
      "threshold": -46.92622950819673,
      "shortcut": [{ "type": 0, "code": 12, "name": "i" }],
      "delay": 98.36065573770492
    },
    "automatic_gain_control": false,
    "echo_cancellation": false,
    "noise_suppression": false,
    "qos": false,
    "silence_warning": false,
    "deaf": false,
    "mute": false
  },
  "nonce": "fa07c532-bb03-4f75-8b9a-397f5109afb6"
}

SET_VOICE_SETTINGS

When setting voice settings, all fields are optional. Only passed fields are updated.

Set Voice Settings Argument and Response Structure

Field	Type	Description
input	voice settings input object	input settings
output	voice settings output object	output settings
mode	voice settings mode object	voice mode settings
automatic_gain_control	boolean	state of automatic gain control
echo_cancellation	boolean	state of echo cancellation
noise_suppression	boolean	state of noise suppression
qos	boolean	state of voice quality of service
silence_warning	boolean	state of silence warning notice
deaf	boolean	state of self-deafen
mute	boolean	state of self-mute

Example Set Voice Settings Command Payload

JSON

{
  "nonce": "3d64ed55-ef6e-4bd5-99c9-677533babc22",
  "args": {
    "input": {
      "volume": 90.5
    }
  },
  "cmd": "SET_VOICE_SETTINGS"
}

Example Set Voice Settings Response Payload

JSON

{
  "cmd": "SET_VOICE_SETTINGS",
  "data": {
    "input": {
      "available_devices": [
        {
          "id": "default",
          "name": "Default"
        },
        {
          "id": "Built-in Microphone",
          "name": "Built-in Microphone"
        }
      ],
      "device_id": "default",
      "volume": 90.5
    },
    "output": {
      "available_devices": [
        {
          "id": "default",
          "name": "Default"
        },
        {
          "id": "Built-in Output",
          "name": "Built-in Output"
        }
      ],
      "device_id": "default",
      "volume": 93.00000071525574
    },
    "mode": {
      "type": "VOICE_ACTIVITY",
      "auto_threshold": true,
      "threshold": -46.92622950819673,
      "shortcut": [{ "type": 0, "code": 12, "name": "i" }],
      "delay": 98.36065573770492
    },
    "automatic_gain_control": false,
    "echo_cancellation": false,
    "noise_suppression": false,
    "qos": false,
    "silence_warning": false,
    "deaf": false,
    "mute": false
  },
  "nonce": "3d64ed55-ef6e-4bd5-99c9-677533babc22"
}

Used to subscribe to events. evt of the payload should be set to the event being subscribed to. args of the payload should be set to the args needed for the event.

Field	Type	Description
evt	string	event name now subscribed to

JSON

{
  "nonce": "be9a6de3-31d0-4767-a8e9-4818c5690015",
  "args": {
    "guild_id": "199737254929760256"
  },
  "evt": "GUILD_STATUS",
  "cmd": "SUBSCRIBE"
}

JSON

{
  "cmd": "SUBSCRIBE",
  "data": {
    "evt": "GUILD_STATUS"
  },
  "nonce": "be9a6de3-31d0-4767-a8e9-4818c5690015"
}

UNSUBSCRIBE

Used to unsubscribe from events. evt of the payload should be set to the event that was subscribed to. args of the payload should be set to the args needed for the previously subscribed event.

Unsubscribe Response Structure

Field	Type	Description
evt	string	event name now unsubscribed from

Example Unsubscribe Command Payload

JSON

{
  "nonce": "647d814a-4cf8-4fbb-948f-898aad24f55b",
  "args": {
    "guild_id": "199737254929760256"
  },
  "evt": "GUILD_STATUS",
  "cmd": "UNSUBSCRIBE"
}

Example Unsubscribe Response Payload

JSON

{
  "cmd": "UNSUBSCRIBE",
  "data": {
    "evt": "GUILD_STATUS"
  },
  "nonce": "647d814a-4cf8-4fbb-948f-898aad24f55b"
}

SET_CERTIFIED_DEVICES

Used by hardware manufacturers to send information about the current state of their certified devices that are connected to Discord.

Set Certified Devices Argument Structure

Field	Type	Description
devices	array of certified device objects	a list of devices for your manufacturer, in order of priority

Device Object

Field	Type	Description
type	device type	the type of device
id	string	the device's Windows UUID
vendor	vendor object	the hardware vendor
model	model object	the model of the product
related	array of strings	UUIDs of related devices
echo_cancellation?*	boolean	if the device's native echo cancellation is enabled
noise_suppression?*	boolean	if the device's native noise suppression is enabled
automatic_gain_control?*	boolean	if the device's native automatic gain control is enabled
hardware_mute?*	boolean	if the device is hardware muted

*These fields are only applicable for AUDIO_INPUT device types

Vendor Object

Field	Type	Description
name	string	name of the vendor
url	string	url for the vendor

Model Object

Field	Type	Description
name	string	name of the model
url	string	url for the model

Device Type

Type	Value
AUDIO_INPUT	"audioinput"
AUDIO_OUTPUT	"audiooutput"
VIDEO_INPUT	"videoinput"

Example Set Certified Devices Command Payload

JSON

{
  "nonce": "9b4e9711-97f3-4f35-b047-32c82a51978e",
  "cmd": "SET_CERTIFIED_DEVICES",
  "args": {
    "devices": [
      {
        "type": "audioinput",
        "id": "aafc2003-da0e-42a3-b982-6a17a2812510",
        "vendor": {
          "name": "SteelSeries",
          "url": "https://steelseries.com"
        },
        "model": {
          "name": "Arctis 7",
          "url": "https://steelseries.com/gaming-headsets/arctis-7"
        },
        "related": ["aafc2003-da0e-42a3-b982-6a17a2819999"],
        "echo_cancellation": true,
        "noise_suppression": true,
        "automatic_gain_control": true,
        "hardware_mute": false
      }
    ]
  }
}

Example Set Certified Devices Response Payload

JSON

{
  "nonce": "9b4e9711-97f3-4f35-b047-32c82a51978e",
  "cmd": "SET_CERTIFIED_DEVICES",
  "data": null,
  "evt": null
}

SET_ACTIVITY

Used to update a user's Rich Presence.

Set Activity Argument Structure

Field	Type	Description
pid	integer	the application's process id
activity	activity object	the rich presence to assign to the user

Example Set Activity Payload

JSON

{
  "cmd": "SET_ACTIVITY",
  "args": {
    "pid": 9999,
    "activity": {
      "state": "In a Group",
      "state_url": "https://example.com/groups/50335231-9d9d-4ebd-873b-984787ee4d1d",
      "details": "Competitive | In a Match",
      "details_url": "https://example.com/matches/42340203-2f25-4534-8ff6-2a6509e81207",
      "timestamps": {
        "start": time(nullptr),
        "end": time(nullptr) + (60 * 5 + 23)
      },
      "assets": {
        "large_image": "numbani_map",
        "large_text": "Numbani",
        "large_url": "https://example.wiki/maps/Numbani",
        "small_image": "pharah_profile",
        "small_text": "Pharah",
        "small_url": "https://example.wiki/characters/Pharah"
      },
      "party": {
        "id": GameEngine.GetPartyId(),
        "size": [3, 6]
      },
      "secrets": {
        "join": "025ed05c71f639de8bfaa0d679d7c94b2fdce12f",
        "spectate": "e7eb30d2ee025ed05c71ea495f770b76454ee4e0",
        "match": "4b2fdce12f639de8bfa7e3591b71a0d679d7c93f"
      },
      "instance": true
    }
  },
  "nonce": "647d814a-4cf8-4fbb-948f-898abd24f55b"
}

SEND_ACTIVITY_JOIN_INVITE

Used to accept an Ask to Join request.

Send Activity Join Invite Argument Structure

Field	Type	Description
user_id	snowflake	the id of the requesting user

Example Send Activity Join Invite Payload

JSON

{
  "nonce": "5dc0c062-98c6-47a0-8922-15aerg126",
  "cmd": "SEND_ACTIVITY_JOIN_INVITE",
  "args": {
    "user_id": "53908232506183680"
  }
}

CLOSE_ACTIVITY_REQUEST

Used to reject an Ask to Join request.

Close Activity Request Argument Structure

Field	Type	Description
user_id	snowflake	the id of the requesting user

Example Close Activity Request Payload

JSON

{
  "nonce": "5dc0c062-98c6-47a0-8922-15aerg126",
  "cmd": "CLOSE_ACTIVITY_REQUEST",
  "args": {
    "user_id": "53908232506183680"
  }
}

READY

Ready Dispatch Data Structure

Field	Type	Description
v	integer	RPC version
config	rpc server configuration object	server configuration
user	partial user object	the user to whom you are connected

RPC Server Configuration Object

Field	Type	Description
cdn_host	string	server's cdn
api_endpoint	string	server's api endpoint
environment	string	server's environment

Example Ready Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "v": 1,
    "config": {
      "cdn_host": "cdn.discordapp.com",
      "api_endpoint": "//discord.com/api",
      "environment": "production"
    },
    "user": {
      "id": "53908232506183680",
      "username": "Mason",
      "discriminator": "1337",
      "avatar": null
    }
  },
  "evt": "READY"
}

ERROR

Error Data Structure

Field	Type	Description
code	integer	RPC Error Code
message	string	Error description

Example Error Payload

JSON

{
  "cmd": "AUTHORIZE",
  "data": {
    "code": 4007,
    "message": "No client id provided"
  },
  "evt": "ERROR",
  "nonce": "5102b6f0-c769-4f37-8cca-25fb0ab22628"
}

GUILD_STATUS

Guild Status Argument Structure

Field	Type	Description
guild_id	string	id of guild to listen to updates of

Guild Status Dispatch Data Structure

Field	Type	Description
guild	partial guild object	guild with requested id
online	integer	number of online users in guild (deprecated; always 0)

Example Guild Status Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "guild": {
      "id": "199737254929760256",
      "name": "test",
      "icon_url": null
    },
    "online": 0
  },
  "evt": "GUILD_STATUS"
}

GUILD_CREATE

No arguments

Guild Create Dispatch Data Structure

Field	Type	Description
id	string	guild id
name	string	name of the guild

Example Guild Create Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "id": "199737254929767562",
    "name": "Test Server"
  },
  "evt": "GUILD_CREATE"
}

CHANNEL_CREATE

No arguments

Channel Create Dispatch Data Structure

Field	Type	Description
id	string	channel id
name	string	name of the channel
type	integer	channel type (guild text: 0, guild voice: 2, dm: 1, group dm: 3)

Example Channel Create Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "id": "199737254929760257",
    "name": "General",
    "type": 0
  },
  "evt": "CHANNEL_CREATE"
}

VOICE_CHANNEL_SELECT

No arguments

Voice Channel Select Dispatch Data Structure

Field	Type	Description
channel_id	string	id of channel (`null` if none)
guild_id	string	id of guild (`null` if none)

Example Voice Channel Select Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "channel_id": "199737254929760257",
    "guild_id": "199737254929760256"
  },
  "evt": "VOICE_CHANNEL_SELECT"
}

VOICE_SETTINGS_UPDATE

Voice Settings Argument Structure

No arguments. Dispatches the Get Voice Settings response.

Example Voice Settings Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "input": {
      "available_devices": [
        {
          "id": "default",
          "name": "Default"
        },
        {
          "id": "Built-in Microphone",
          "name": "Built-in Microphone"
        }
      ],
      "device_id": "default",
      "volume": 49.803921580314636
    },
    "output": {
      "available_devices": [
        {
          "id": "default",
          "name": "Default"
        },
        {
          "id": "Built-in Output",
          "name": "Built-in Output"
        }
      ],
      "device_id": "default",
      "volume": 93.00000071525574
    },
    "mode": {
      "type": "VOICE_ACTIVITY",
      "auto_threshold": true,
      "threshold": -46.92622950819673,
      "shortcut": [{ "type": 0, "code": 12, "name": "i" }],
      "delay": 98.36065573770492
    },
    "automatic_gain_control": false,
    "echo_cancellation": false,
    "noise_suppression": false,
    "qos": false,
    "silence_warning": false
  },
  "evt": "VOICE_SETTINGS_UPDATE"
}

VOICE_STATE_CREATE/VOICE_STATE_UPDATE/VOICE_STATE_DELETE

Dispatches channel voice state objects

Voice State Argument Structure

Field	Type	Description
channel_id	string	id of channel to listen to updates of

Example Voice State Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "evt": "VOICE_STATE_CREATE",
  "data": {
    "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
    }
  }
}

VOICE_CONNECTION_STATUS

No arguments

Voice Connection Status Dispatch Data Structure

Field	Type	Description
state	string	one of the voice connection states listed below
hostname	string	hostname of the connected voice server
pings	array of integers	last 20 pings (in ms)
average_ping	integer	average ping (in ms)
last_ping	integer	last ping (in ms)

Voice Connection States

Field	Description
DISCONNECTED	TCP disconnected
AWAITING_ENDPOINT	Waiting for voice endpoint
AUTHENTICATING	TCP authenticating
CONNECTING	TCP connecting
CONNECTED	TCP connected
VOICE_DISCONNECTED	TCP connected, Voice disconnected
VOICE_CONNECTING	TCP connected, Voice connecting
VOICE_CONNECTED	TCP connected, Voice connected
NO_ROUTE	No route to host
ICE_CHECKING	WebRTC ice checking

Example Voice Connection Status Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "evt": "VOICE_CONNECTION_STATUS",
  "data": {
    "state": "VOICE_CONNECTED",
    "hostname": "some-server.discord.gg",
    "pings": [20, 13.37],
    "average_ping": 13.37,
    "last_ping": 20
  }
}

MESSAGE_CREATE/MESSAGE_UPDATE/MESSAGE_DELETE

Dispatches message objects, with the exception of deletions, which only contains the id in the message object.

Message Argument Structure

Field	Type	Description
channel_id	string	id of channel to listen to updates of

Example Message Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "channel_id": "199737254929760256",
    "message": {
      "id": "199743874640379904",
      "blocked": false,
      "content": "test",
      "content_parsed": [
        {
          "content": "test",
          "type": "text"
        }
      ],
      "author_color": "#ffffff",
      "edited_timestamp": null,
      "timestamp": "2016-07-05T04:30:50.776Z",
      "tts": false,
      "mentions": [],
      "mention_roles": [],
      "mention_everyone": false,
      "embeds": [],
      "attachments": [],
      "type": 0,
      "pinned": false,
      "author": {
        "id": "190320984123768832",
        "username": "test user 2",
        "discriminator": "7479",
        "avatar": "b004ec1740a63ca06ae2e14c5cee11f3",
        "bot": false
      }
    }
  },
  "evt": "MESSAGE_CREATE"
}

SPEAKING_START/SPEAKING_STOP

Speaking Argument Structure

Field	Type	Description
channel_id	string	id of channel to listen to updates of

Speaking Dispatch Data Structure

Field	Type	Description
user_id	string	id of user who started/stopped speaking

Example Speaking Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "user_id": "190320984123768832"
  },
  "evt": "SPEAKING_STOP"
}

NOTIFICATION_CREATE

No arguments. This event requires the rpc.notifications.read OAuth2 scope.

Notification Create Dispatch Data Structure

Field	Type	Description
channel_id	string	id of channel where notification occurred
message	message object	message that generated this notification
icon_url	string	icon url of the notification
title	string	title of the notification
body	string	body of the notification

Example Notification Create Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "channel_id": "199737254929760256",
    "message": {
      "id": "199743874640379904",
      "blocked": false,
      "content": "test",
      "content_parsed": [
        {
          "content": "test",
          "type": "text"
        }
      ],
      "author_color": "#ffffff",
      "edited_timestamp": null,
      "timestamp": "2016-07-05T04:30:50.776Z",
      "tts": false,
      "mentions": [],
      "mention_roles": [],
      "mention_everyone": false,
      "embeds": [],
      "attachments": [],
      "type": 0,
      "pinned": false,
      "author": {
        "id": "190320984123768832",
        "username": "test user 2",
        "discriminator": "7479",
        "avatar": "b004ec1740a63ca06ae2e14c5cee11f3",
        "bot": false
      }
    },
    "icon_url": "https://cdn.discordapp.com/avatars/155607406007681024/8ab559b8286e48270c04471ae382cd9d.jpg",
    "title": "test_user (#general)",
    "body": "test message"
  },
  "evt": "NOTIFICATION_CREATE"
}

ACTIVITY_JOIN

No arguments

Activity Join Dispatch Data Structure

Field	Type	Description
secret	string	the `join_secret` for the given invite

Example Activity Join Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "secret": "025ed05c71f639de8bfaa0d679d7c94b2fdce12f"
  },
  "evt": "ACTIVITY_JOIN"
}

ACTIVITY_SPECTATE

No arguments

Activity Spectate Dispatch Data Structure

Field	Type	Description
secret	string	the `spectate_secret` for the given invite

Example Activity Spectate Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "secret": "e7eb30d2ee025ed05c71ea495f770b76454ee4e0"
  },
  "evt": "ACTIVITY_SPECTATE"
}

ACTIVITY_JOIN_REQUEST

No arguments

Activity Join Request Data Structure

Field	Type	Description
user	partial user object	information about the user requesting to join

Example Activity Join Request Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "user": {
      "id": "53908232506183680",
      "username": "Mason",
      "discriminator": "1337",
      "avatar": "a_bab14f271d565501444b2ca3be944b25"
    }
  },
  "evt": "ACTIVITY_JOIN_REQUEST"
}

ACTIVITY_INVITE

No arguments

Activity Invite Dispatch Data Structure

Field	Type	Description
type	integer	invite type; `1` for join
user	partial user object	user who sent the invite
activity	activity object	the activity associated with the invite
channel_id	string	id of the channel the invite was sent in
message_id	string	id of the invite message

Example Activity Invite Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "type": 1,
    "user": {
      "id": "53908232506183680",
      "username": "Mason",
      "discriminator": "1337",
      "avatar": "a_bab14f271d565501444b2ca3be944b25"
    },
    "activity": {
      "application_id": "192741864418312192",
      "name": "My Game",
      "party": {
        "id": "party1234",
        "size": [2, 5]
      }
    },
    "channel_id": "199737254929760256",
    "message_id": "199743874640379904"
  },
  "evt": "ACTIVITY_INVITE"
}

CURRENT_USER_UPDATE

No arguments. Dispatches the current user's profile whenever it changes (avatar, username, etc.).

Current User Update Dispatch Data Structure

Field	Type	Description
id	string	user's id
username	string	user's username
discriminator	string	user's discriminator
global_name	string	user's display name
avatar	string	user's avatar hash
avatar_decoration_data	object	avatar decoration data, if any (`null` if none)
bot	boolean	whether the user is a bot
flags	integer	the public flags on a user's account
premium_type	integer	type of Nitro subscription. Requires `identify.premium` scope.

Example Current User Update Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "id": "53908232506183680",
    "username": "Mason",
    "discriminator": "0",
    "global_name": "Mason",
    "avatar": "a_bab14f271d565501444b2ca3be944b25",
    "avatar_decoration_data": null,
    "bot": false,
    "flags": 64,
    "premium_type": 0
  },
  "evt": "CURRENT_USER_UPDATE"
}

RELATIONSHIP_UPDATE

No arguments. Requires the relationships_read OAuth2 scope.

Fired when a relationship is added, updated (e.g. presence change), or removed. When a relationship is removed, type will be 0 (NONE).

Relationship Update Dispatch Data Structure

Field	Type	Description
type	integer	relationship type
user	partial user object	the related user
presence	presence object	the related user's current presence

Relationship Types

Type	Value	Description
NONE	0	relationship removed
FRIEND	1	user is a friend
BLOCKED	2	user is blocked
PENDING_INCOMING	3	incoming friend request
PENDING_OUTGOING	4	outgoing friend request
IMPLICIT	5	user is in a mutual guild (not a friend)

Presence Object

Field	Type	Description
status	string	user's status (`online`, `idle`, `dnd`, `offline`)
activity	activity object	user's current activity for this application (`null` if none)

Example Relationship Update Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "type": 1,
    "user": {
      "id": "190320984123768832",
      "username": "test user 2",
      "discriminator": "0",
      "global_name": "test user 2",
      "avatar": "b004ec1740a63ca06ae2e14c5cee11f3",
      "bot": false,
      "flags": 0,
      "premium_type": 0
    },
    "presence": {
      "status": "online",
      "activity": null
    }
  },
  "evt": "RELATIONSHIP_UPDATE"
}

ENTITLEMENT_CREATE

No arguments. Fired when the user acquires a new entitlement for this application.

Entitlement Create Dispatch Data Structure

Field	Type	Description
entitlement	entitlement object	the entitlement that was created

Entitlement Object

Field	Type	Description
id	string	entitlement id
sku_id	string	id of the SKU this entitlement is for
application_id	string	id of the application
user_id	string	id of the user that owns the entitlement
type	integer	entitlement type
deleted	boolean	whether the entitlement has been deleted
starts_at?	ISO8601	start date of the entitlement
ends_at?	ISO8601	end date of the entitlement
guild_id?	string	id of the guild the entitlement applies to
consumed?	boolean	for consumable entitlements, whether the entitlement has been consumed

Entitlement Types

Type	Value	Description
PURCHASE	1	purchased by a user
PREMIUM_SUBSCRIPTION	2	a Nitro subscription
DEVELOPER_GIFT	3	gifted by a developer
TEST_MODE_PURCHASE	4	purchased in test mode
FREE_PURCHASE	5	granted for free
USER_GIFT	6	gifted by another user
PREMIUM_PURCHASE	7	purchased as a premium feature
APPLICATION_SUBSCRIPTION	8	an app subscription

Example Entitlement Create Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "entitlement": {
      "id": "1019653849998299136",
      "sku_id": "1019475255913222144",
      "application_id": "192741864418312192",
      "user_id": "53908232506183680",
      "type": 8,
      "deleted": false,
      "starts_at": "2022-09-14T17:00:18.704163+00:00",
      "ends_at": "2022-10-14T17:00:18.704163+00:00"
    }
  },
  "evt": "ENTITLEMENT_CREATE"
}

ENTITLEMENT_DELETE

No arguments. Fired when an entitlement for this application is removed. The entitlement object in the payload reflects the state of the entitlement at the time of deletion.

Entitlement Delete Dispatch Data Structure

Field	Type	Description
entitlement	entitlement object	the entitlement that was deleted

Example Entitlement Delete Dispatch Payload

JSON

{
  "cmd": "DISPATCH",
  "data": {
    "entitlement": {
      "id": "1019653849998299136",
      "sku_id": "1019475255913222144",
      "application_id": "192741864418312192",
      "user_id": "53908232506183680",
      "type": 8,
      "deleted": true,
      "starts_at": "2022-09-14T17:00:18.704163+00:00",
      "ends_at": "2022-10-14T17:00:18.704163+00:00"
    }
  },
  "evt": "ENTITLEMENT_DELETE"
}

RPC over IPC

IPC Path

Connecting to IPC

Handshake Payload

Example Handshake

Opcodes

Connecting to WebSocket

RPC Server Ports

RPC Versions

Restrictions

Payloads

Payload Structure

Authenticating

RPC Authorize Example

RPC Authenticate Example

Commands and Events

RPC Commands

RPC Events

AUTHORIZE

Authorize Argument Structure

Authorize Response Structure

Example Authorize Command Payload

Example Authorize Response Payload

AUTHENTICATE

Authenticate Argument Structure

Authenticate Response Structure

OAuth2 Application Structure

Example Authenticate Command Payload

Example Authenticate Response Payload

GET_GUILDS

Get Guilds Response Structure

Example Get Guilds Command Payload

Example Get Guilds Response Payload

GET_GUILD

Get Guild Argument Structure

Get Guild Response Structure

Example Get Guild Command Payload

Example Get Guild Response Payload

GET_CHANNEL

Get Channel Argument Structure

Get Channel Response Structure

Example Get Channel Command Payload

Example Get Channel Response Payload

GET_CHANNELS

Get Channels Argument Structure

Get Channels Response Structure

Example Get Channels Command Payload

Example Get Channels Response Payload

SET_USER_VOICE_SETTINGS

Set User Voice Settings Argument and Response Structure

Pan Object

Example Set User Voice Settings Command Payload

Example Set User Voice Settings Response Payload

SELECT_VOICE_CHANNEL

Select Voice Channel Argument Structure

Example Select Voice Channel Command Payload

Example Select Voice Channel Response Payload

GET_SELECTED_VOICE_CHANNEL

SELECT_TEXT_CHANNEL

Select Text Channel Argument Structure

GET_VOICE_SETTINGS

Get Voice Settings Response Structure

Voice Settings Input Object

Voice Settings Output Object

Voice Settings Mode Object

Shortcut Key Combo Object

Key Types

Example Get Voice Settings Response Payload

SET_VOICE_SETTINGS

Set Voice Settings Argument and Response Structure

Example Set Voice Settings Command Payload

Example Set Voice Settings Response Payload

SUBSCRIBE

Subscribe Response Structure

Example Subscribe Command Payload

Example Subscribe Response Payload

UNSUBSCRIBE

Unsubscribe Response Structure

Example Unsubscribe Command Payload

Example Unsubscribe Response Payload