RPC

For now, RPC is in a private beta, which means that only apps that have signed up and been approved can access it. If you're interested in trying out Discord to power your game, please sign up here.
RPC Versions
VersionOut of Service
1no
All Discord clients have an RPC server running on localhost that allows control over local Discord clients. Most games will want to use our GameBridge SDK in combination, since it offers the power of Discord to players who don't have Discord yet installed. In addition to the documentation below, we have put together a sample project that shows the basics of using the RPC within a game. Check it out if you'd like to see how all of these concepts come together.

Topics

  1. Payloads
  2. Connecting
  3. Authenticating
  4. Proxied API Requests
  5. Commands and Events

Restrictions

For connections to the RPC server, a whitelist is used to restrict access while you're still developing. You can invite up to 50 people to your whitelist.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
FieldTypeDescriptionPresent
cmdenumpayload commandAlways
noncestringunique string used once for replies from the serverIn responses to commands (not subscribed events)
evtenumsubscription eventIn subscribed events, errors, and (un)subscribing events
dataobjectevent dataIn responses from the server
argsobjectcommand argumentsIn 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://discordapp.com would be used if the user were connecting from https://discordapp.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://discordapp.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.api", "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://discordapp.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!

Proxied API Requests

If you request the rpc.api scope when authorizing your app to the client, your app is able to call the Discord API on behalf of the user whose access token you retrieved.For proxied API requests, the schema, host, and path to the API endpoint is always http://127.0.0.1:PORT/ where PORT is the same port on which the RPC server is listening.Proxied API requests accept an OAuth2 Bearer token in the Authorization header and respond as our API normally does. However, they are executed with the user's bearer token instead of a bot token, providing the ability to modify most of what the client has access to.
Example RPC Proxy Call
curl -H 'Authorization: Bearer CZhtkLDpNYXgPH9Ml6shqh2OwykChw' http://127.0.0.1:6463/users/@me/guilds

[{
    "owner": true,
    "permissions": 2146958399,
    "icon": "2d68b25aa5d1eead693432a5f0077dff",
    "id": "199737254929760256",
    "name": "test"
}]
Certain endpoints deemed potentially unsafe—like authorization and user management—are blocked. Check out the rest of our API docs to learn more about interfacing with our REST API.

Commands and Events

Commands are requests made to the RPC socket by a client.
RPC Commands
NameDescription
DISPATCHevent dispatch
AUTHORIZEused to authorize a new client with your app
AUTHENTICATEused to authenticate an existing client with your app
GET_GUILDused to retrieve guild information from the client
GET_GUILDSused to retrieve a list of guilds from the client
GET_CHANNELused to retrieve channel information from the client
GET_CHANNELSused to retrieve a list of channels for a guild from the client
SUBSCRIBEused to subscribe to an RPC event
UNSUBSCRIBEused to unsubscribe from an RPC event
SET_USER_VOICE_SETTINGSused to change voice settings of users in voice channels
SELECT_VOICE_CHANNELused to join or leave a voice channel, group dm, or dm
GET_SELECTED_VOICE_CHANNELused to get the current voice channel the client is in
SELECT_TEXT_CHANNELused to join or leave a text channel, group dm, or dm
GET_VOICE_SETTINGSused to retrieve the client's voice settings
SET_VOICE_SETTINGSused to set the client's voice settings
CAPTURE_SHORTCUTused to capture a keyboard shortcut entered by the user
Events are payloads sent over the socket to a client that correspond events in Discord.
RPC Events
NameDescription
READYnon-subscription event sent immediately after connecting, contains server information
ERRORnon-subscription event sent when there is an error, including command responses
GUILD_STATUSsent when a subscribed server's state changes
GUILD_CREATEsent when a guild is created/joined on the client
CHANNEL_CREATEsent when a channel is created/joined on the client
VOICE_CHANNEL_SELECTsent when the client joins a voice channel
VOICE_STATE_CREATEsent when a user joins a subscribed voice channel
VOICE_STATE_UPDATEsent when a user's voice state changes in a subscribed voice channel (mute, volume, etc.)
VOICE_STATE_DELETEsent when a user parts a subscribed voice channel
VOICE_SETTINGS_UPDATEsent when the client's voice settings update
VOICE_CONNECTION_STATUSsent when the client's voice connection status changes
SPEAKING_STARTsent when a user in a subscribed voice channel speaks
SPEAKING_STOPsent when a user in a subscribed voice channel stops speaking
MESSAGE_CREATEsent when a message is created in a subscribed text channel
MESSAGE_UPDATEsent when a message is updated in a subscribed text channel
MESSAGE_DELETEsent when a message is deleted in a subscribed text channel
NOTIFICATION_CREATEsent when the client receives a notification (mention or new message in eligible channels)
CAPTURE_SHORTCUT_CHANGEsent when the user presses a key during shortcut capturing

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 games without an entry on a game's whitelist. We grant 50 whitelist spots, which should be ample for development and testing. After approval, this restriction is removed and the whitelist is no longer needed.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 whitelist, and also disallows use of the messages.read scope. If you have been granted access, you can send a POST request to https://discordapp.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
FieldTypeDescription
scopesarray of OAuth2 scopesscopes to authorize
client_idstringOAuth2 application id
rpc_tokenstringone-time use RPC token
usernamestringusername to create a guest account with if the user does not have Discord (only in GameBridge SDK)
Authorize Response Structure
FieldTypeDescription
codestringOAuth2 authorization code
Example Authorize Command Payload
{
    "nonce": "f48f6176-4afb-4c03-b1b8-d960861f5216",
    "args": {
        "client_id": "192741864418312192",
        "scopes": ["rpc.api", "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
FieldTypeDescription
access_tokenstringOAuth2 access token
Authenticate Response Structure
FieldTypeDescription
userpartial user objectthe authed user
scopesarray of OAuth2 scopesauthorized scopes
expiresdateexpiration date of OAuth2 token
applicationOAuth2 application objectapplication the user authorized
OAuth2 Application Structure
FieldTypeDescription
descriptionstringapplication description
iconstringhash of the icon
idsnowflakeapplication client id
rpc_originsarrayarray of strings -
namestringapplication 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.api", "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
FieldTypeDescription
guildsarray of partial guild objectsthe 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
FieldTypeDescription
guild_idstringid of the guild to get
timeoutintegerasyncronously get guild with time to wait before timing out
Get Guild Response Structure
FieldTypeDescription
idstringguild id
namestringguild name
icon_urlstringguild icon url
membersarray of guild member objectsmembers of the guild
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": [{
            "user": {
                "id": "190320984123768832",
                "username": "test 2",
                "discriminator": "7479",
                "avatar": "b004ec1740a63ca06ae2e14c5cee11f3",
                "bot": false
            },
            "status": "online",
            "activity": null
        }, {
            "user": {
                "id": "192731515703001088",
                "username": "test",
                "discriminator": "5844",
                "avatar": null,
                "bot": false
            },
            "status": "idle",
            "activity": null
        }]
    },
    "nonce": "9524922c-3d32-413a-bdaa-0804f4332588"
}

GET_CHANNEL

Used to get a channel the client is in.
Get Channel Argument Structure
FieldTypeDescription
channel_idstringid of the channel to get
Get Channel Response Structure
FieldTypeDescription
idstringchannel id
guild_idstringchannel's guild id
namestringchannel name
typeintegerchannel type (guild text: 0, guild voice: 2, dm: 1, group dm: 3)
topicstring(text) channel topic
bitrateinteger(voice) bitrate of voice channel
user_limitinteger(voice) user limit of voice channel (0 for none)
positionintegerposition of channel in channel list
voice_statesarray of voice state objects(voice) channel's voice states
messagesarray 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
FieldTypeDescription
guild_idstringid of the guild to get channels for
Get Channels Response Structure
FieldTypeDescription
channelsarray of partial channel objectsguild 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
FieldTypeDescription
user_idstringuser id
pan?pan objectset the pan of the user
volume?integerset the volume of user (defaults to 100, min 0, max 200)
mute?boolset 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
FieldTypeDescription
leftfloatleft pan of user (min: 0.0, max: 1.0)
rightfloatright 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
Select Voice Channel Argument Structure
FieldTypeDescription
channel_idstringchannel id to join (or null to leave)
timeoutintegerasyncronously join channel with time to wait before timing out
forceboolforces a user to join a voice channel
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.
Select Voice Channel Response Structure
Returns the Get Channel response, null if none.
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
FieldTypeDescription
channel_idstringchannel id to join (or null to leave)
timeoutintegerasyncronously join channel with time to wait before timing out

GET_VOICE_SETTINGS

Get Voice Settings Response Structure
FieldTypeDescription
inputvoice settings input objectinput settings
outputvoice settings ouputoutput settings
modevoice settings mode objectvoice mode settings
automatic_gain_controlboolstate of automatic gain control
echo_cancellationboolstate of echo cancellation
noise_suppressionboolstate of noise suppression
qosboolstate of voice quality of service
silence_warningboolstate of silence warning notice
deafboolstate of self-deafen
muteboolstate of self-mute
Voice Settings Input Object
FieldTypeDescription
device_idstringdevice id
volumefloatinput voice level (min: 0, max: 100)
available_devicesarrayarray of read-only device objects containing id and name string keys
Voice Settings Output Object
FieldTypeDescription
device_idstringdevice id
volumefloatoutput voice level (min: 0, max: 200)
available_devicesarrayarray of read-only device objects containing id and name string keys
Voice Settings Mode Object
FieldTypeDescription
typestringvoice setting mode type (can be PUSH_TO_TALK or VOICE_ACTIVITY)
auto_thresholdboolvoice activity threshold automatically sets its threshold
thresholdfloatthreshold for voice activity (in dB) (min: -100, max: 0)
shortcutshortcut key combo objectshortcut key combos for PTT
delayfloatthe PTT release delay (in ms) (min: 0, max: 2000)
Shortcut Key Combo Object
FieldTypeDescription
typeintegersee key types
codeintegerkey code
namestringkey name
Key Types
TypeId
KEYBOARD_KEY0
MOUSE_BUTTON1
KEYBOARD_MODIFIER_KEY2
GAMEPAD_BUTTON3
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

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.
When setting voice settings, all fields are optional. Only passed fields are updated.
Set Voice Settings Argument and Response Structure
FieldTypeDescription
inputvoice settings input objectinput settings
outputvoice settings ouputoutput settings
modevoice settings mode objectvoice mode settings
automatic_gain_controlboolstate of automatic gain control
echo_cancellationboolstate of echo cancellation
noise_suppressionboolstate of noise suppression
qosboolstate of voice quality of service
silence_warningboolstate of silence warning notice
deafboolstate of self-deafen
muteboolstate 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"
}

SUBSCRIBE

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
FieldTypeDescription
evtstringevent 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
FieldTypeDescription
evtstringevent 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"
}

CAPTURE_SHORTCUT

Used to capture a keyboard shortcut entered by the user.This command is asynchronously returned. You capture a shortcut by first sending the START action. Then, the user is free to press keys while we log the shortcut key codes for you. As they press keys, we will emit a CAPTURE_SHORTCUT_CHANGE event with the updated key codes. When the user finishes, you then need to finish capturing by sending the STOP action.Returns the shortcut captured, and null for the STOP action.Note: The START call will return the captured shortcut in its data object, while the STOP call will have no data.
Capture Shortcut Argument Structure
FieldTypeDescription
actionstringcapture action; START or STOP
Capture Shortcut Response Structure
FieldTypeDescription
shortcutshortcut key combo objectthe captured shortcut key combo array
Example Capture Shortcut Command Payload
{
    "nonce": "9b4e9711-97f3-4f35-b047-32c82a51978e",
    "args": {
        "action": "START"
    },
    "cmd": "CAPTURE_SHORTCUT"
}
Example Capture Shortcut Response Payload
{
    "cmd": "CAPTURE_SHORTCUT",
    "data": {
        "shortcut": [{"type":0,"code":12,"name":"i"}]
    },
    "nonce": "9b4e9711-97f3-4f35-b047-32c82a51978e"
}

READY

Ready Dispatch Data Structure
FieldTypeDescription
vintegerRPC version
configrpc server configuration objectserver configuration
RPC Server Configuration Object
FieldTypeDescription
cdn_hoststringserver's cdn
api_endpointstringserver's api endpoint
environmentstringserver's environment
Example Ready Dispatch Payload
{
    "cmd": "DISPATCH",
    "data": {
        "v": 1,
        "config": {
            "cdn_host": "cdn.discordapp.com",
            "api_endpoint": "//discordapp.com/api",
            "environment": "production"
        }
    },
    "evt": "READY"
}

ERROR

Error Data Structure
FieldTypeDescription
codeintegerRPC Error Code
messagestringError 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
FieldTypeDescription
guild_idstringid of guild to listen to updates of
Guild Status Dispatch Data Structure
FieldTypeDescription
guildpartial guildguild with requested id
onlineintegernumber of online users in guild
Example Guild Status Dispatch Payload
{
    "cmd": "DISPATCH",
    "data": {
        "guild": {
            "id": "199737254929760256",
            "name": "test",
            "icon_url": null
        },
        "online": 2
    },
    "evt": "GUILD_STATUS"
}

GUILD_CREATE

No arguments
Guild Create Dispatch Data Structure
FieldTypeDescription
idstringguild id
namestringname 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
FieldTypeDescription
idstringchannel id
namestringname of the channel
typeintegerchannel 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
FieldTypeDescription
channel_idstringid of channel (null if none)
guild_idstringid 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
FieldTypeDescription
channel_idstringid 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
FieldTypeDescription
statestringone of the voice connection states listed below
hostnamestringhostname of the connected voice server
pingsarray of integerslast 20 pings (in ms)
average_pingintegeraverage ping (in ms)
last_pingintegerlast ping (in ms)
Voice Connection States
FieldDescription
DISCONNECTEDTCP disconnected
AWAITING_ENDPOINTWaiting for voice endpoint
AUTHENTICATINGTCP authenticating
CONNECTINGTCP connecting
CONNECTEDTCP connected
VOICE_DISCONNECTEDTCP connected, Voice disconnected
VOICE_CONNECTINGTCP connected, Voice connecting
VOICE_CONNECTEDTCP connected, Voice connected
NO_ROUTENo route to host
ICE_CHECKINGWebRTC 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
FieldTypeDescription
channel_idstringid 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
FieldTypeDescription
channel_idstringid of channel to listen to updates of
Speaking Dispatch Data Structure
FieldTypeDescription
user_idstringid 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
FieldTypeDescription
channel_idstringid of channel where notification occurred
messagemessage objectmessage that generated this notification
icon_urlstringicon url of the notification
titlestringtitle of the notification
bodystringbody 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"
}

CAPTURE_SHORTCUT_CHANGE

No arguments
Capture Shortcut Change Dispatch Data Structure
FieldTypeDescription
shortcutarray of shortcut key combo objectscaptured shortcut key combos
Example Capture Shortcut Change Dispatch Payload
{
    "cmd": "DISPATCH",
    "evt": "CAPTURE_SHORTCUT_CHANGE",
    "data": {
        "shortcut": [{"type":0,"code":12,"name":"i"}]
    }
}