RPC

For now, RPC is in a private beta. We are not currently accepting any new developers into the program at this time.

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

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

Connecting

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.

Authenticating

In order to call any commands over RPC, you must be authenticated or you will receive a code 4006 error response. Thankfully, we’ve removed the oppressive nature of a couple commands that will let you AUTHORIZE and AUTHENTICATE new users. First, call AUTHORIZE:

RPC Authorize Example

{
  "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

{
  "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
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

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

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

Example Authorize Response Payload

{
  "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

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

Example Authenticate Response Payload

{
  "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

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

Example Get Guilds Response Payload

{
  "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

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

Example Get Guild Response Payload

{
  "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

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

Example Get Channel Response Payload

{
  "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

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

Example Get Channels Response Payload

{
  "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

In the current release, we only support a single modifier of voice settings at a time over RPC. If an app changes voice settings, it will lock voice settings so that other apps connected simultaneously lose the ability to change voice settings. Settings reset to what they were before being changed after the controlling app disconnects. When an app that has previously set voice settings connects, the client will swap to that app’s configured voice settings and lock voice settings again. This is a temporary situation that will be changed in the future.

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

{
  "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

{
  "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

When trying to join the user to a voice channel, you will receive a 5003 error coded response if the user is already in a voice channel. The force parameter should only be specified in response to the case where a user is already in a voice channel and they have approved to be moved by your app to a new voice channel.

Example Select Voice Channel Command Payload

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

Example Select Voice Channel Response Payload

{
  "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

{
  "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

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

Example Set Voice Settings Response Payload

{
  "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.

Subscribe Response Structure

Field	Type	Description
evt	string	event name now subscribed to

Example Subscribe Command Payload

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

Example Subscribe Response Payload

{
  "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

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

Example Unsubscribe Response Payload

{
  "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

{
  "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

{
  "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

When using SET_ACTIVITY, the activity object is limited to a type of Playing (0), Listening (2), Watching (3), or Competing (5).

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

Home

Quick Start

Interactions

Components

Activities

Discord Social SDK

Rich Presence

Monetization

Discovery

Events

Developer Tools

Resources

Topics

Tutorials

Policies and Agreements

​RPC

RPC Versions

​Restrictions

​Payloads

Payload Structure

​Connecting

​RPC Server Ports

​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

RPC

Restrictions

Payloads

Connecting

RPC Server Ports

Authenticating

Commands and Events

AUTHORIZE

AUTHENTICATE

GET_GUILDS

GET_GUILD

GET_CHANNEL

GET_CHANNELS

SET_USER_VOICE_SETTINGS

SELECT_VOICE_CHANNEL

GET_SELECTED_VOICE_CHANNEL

SELECT_TEXT_CHANNEL

GET_VOICE_SETTINGS

SET_VOICE_SETTINGS

SUBSCRIBE

UNSUBSCRIBE

SET_CERTIFIED_DEVICES

SET_ACTIVITY

SEND_ACTIVITY_JOIN_INVITE

CLOSE_ACTIVITY_REQUEST

READY

ERROR

GUILD_STATUS

GUILD_CREATE

CHANNEL_CREATE

VOICE_CHANNEL_SELECT

VOICE_SETTINGS_UPDATE

VOICE_STATE_CREATE/VOICE_STATE_UPDATE/VOICE_STATE_DELETE

VOICE_CONNECTION_STATUS

MESSAGE_CREATE/MESSAGE_UPDATE/MESSAGE_DELETE

SPEAKING_START/SPEAKING_STOP

NOTIFICATION_CREATE

ACTIVITY_JOIN