Skip to content

Commit 86d1f28

Browse files
5XS5XS
authored
Document RPC over IPC (#8246)
* feat: Information about RPC over IPC * fix: accordion * fix: wrong placed spaces in table * unwanted lines removal * return back links * return links for rpc commands
1 parent d68b90f commit 86d1f28

1 file changed

Lines changed: 101 additions & 46 deletions

File tree

‎developers/topics/rpc.mdx‎

Lines changed: 101 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -6,39 +6,62 @@ description: Learn about Discord's RPC server for local application integration.
66
import {ManualAnchor} from '/snippets/manualanchor.jsx'
77

88

9-
<Danger>
10-
For now, RPC is in a private beta. We are not currently accepting any new developers into the program at this time.
11-
</Danger>
9+
## RPC over IPC
1210

13-
All Discord clients have an RPC server running on localhost that allows control over local Discord clients.
11+
Discord's RPC server supports IPC (Inter-Process Communication) as the primary transport for native applications and games. This allows high-performance, local communication with the Discord client without requiring network-level overhead.
1412

15-
<ManualAnchor id="rpc-versions" />
16-
###### RPC Versions
13+
###### IPC Path
1714

18-
| Version | Out of Service |
19-
|---------|----------------|
20-
| 1 | no |
15+
| Platform | Path Format |
16+
|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
17+
| Windows | `\\?\pipe\discord-ipc-{n}` |
18+
| 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}` |
2119

22-
## Restrictions
20+
On Linux/macOS, Discord resolves the IPC prefix in this order: `XDG_RUNTIME_DIR`, `TMPDIR`, `TMP`, `TEMP`, then `/tmp` as a final fallback.
2321

24-
For connections to the RPC server, a [list of approved testers](/developers/topics/rpc#authorize) is used to restrict access while you're still developing. You can invite up to 50 people.
22+
### Connecting to IPC
2523

26-
For applications/games not approved, we limit you to creating 10 guilds and 10 channels. This limit is raised to virtually unlimited after approval.
24+
To begin a session, the application must open the IPC socket and send a `HANDSHAKE` opcode.
2725

28-
## Payloads
26+
#### Handshake Payload
2927

30-
<ManualAnchor id="payloads-payload-structure" />
31-
###### Payload Structure
28+
The payload is a JSON object containing the RPC version and your application's client ID.
3229

33-
| Field | Type | Description | Present |
34-
|-------|--------|-----------------------------------------------------------------------------|----------------------------------------------------------|
35-
| cmd | enum | [payload command](/developers/topics/rpc#commands-and-events-rpc-commands) | Always |
36-
| nonce | string | unique string used once for replies from the server | In responses to commands (not subscribed events) |
37-
| evt | enum | [subscription event](/developers/topics/rpc#commands-and-events-rpc-events) | In subscribed events, errors, and (un)subscribing events |
38-
| data | object | event data | In responses from the server |
39-
| args | object | command arguments | In commands sent to the server |
30+
| Field | Type | Description |
31+
|-------------|-----------|------------------------------|
32+
| `v` | `integer` | RPC version |
33+
| `client_id` | `string` | Your application's client ID |
34+
35+
###### Example Handshake
36+
37+
```
38+
[00 00 00 00] // Opcode 0 (Handshake)
39+
[2D 00 00 00] // Length 45
40+
{"v":1,"client_id":"123456789012345678"}
41+
```
42+
43+
Upon success, Discord will respond with a `FRAME` (Opcode `1`) containing the `READY` event.
44+
45+
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](/developers/topics/rpc#payloads-payload-structure)
46+
47+
###### Opcodes
48+
49+
| Opcode | Name | Description |
50+
|--------|-------------|-----------------------------------------------|
51+
| `0` | `HANDSHAKE` | Sent by the client to initiate the connection |
52+
| `1` | `FRAME` | Used for all standard RPC commands and events |
53+
| `2` | `CLOSE` | Sent by either side to close the connection |
54+
| `3` | `PING` | Sent to check if the connection is alive |
55+
| `4` | `PONG` | Response to a `PING` |
56+
57+
<Accordion title="RPC over WebSocket (Deprecated)" icon="warning">
58+
<Danger>
59+
This is a deprecated way, which is only available for old participants of private beta. It is preferable to use RPC that uses IPC.
60+
</Danger>
61+
62+
All Discord clients have an RPC server running on localhost that allows control over local Discord clients.
4063

41-
## Connecting
64+
### Connecting to WebSocket
4265

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

@@ -61,6 +84,33 @@ If you're connecting to the RPC server from within a non-browser application (li
6184

6285
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.
6386

87+
<ManualAnchor id="rpc-versions" />
88+
###### RPC Versions
89+
90+
| Version | Out of Service |
91+
|---------|----------------|
92+
| 1 | no |
93+
</Accordion>
94+
95+
## Restrictions
96+
97+
For connections to the RPC server, a [list of approved testers](/developers/topics/rpc#authorize) is used to restrict access while you're still developing. You can invite up to 50 people.
98+
99+
For applications/games not approved, we limit you to creating 10 guilds and 10 channels. This limit is raised to virtually unlimited after approval.
100+
101+
## Payloads
102+
103+
<ManualAnchor id="payloads-payload-structure" />
104+
###### Payload Structure
105+
106+
| Field | Type | Description | Present |
107+
|-------|--------|-----------------------------------------------------------------------------|----------------------------------------------------------|
108+
| cmd | enum | [payload command](/developers/topics/rpc#commands-and-events-rpc-commands) | Always |
109+
| nonce | string | unique string used once for replies from the server | In responses to commands (not subscribed events) |
110+
| evt | enum | [subscription event](/developers/topics/rpc#commands-and-events-rpc-events) | In subscribed events, errors, and (un)subscribing events |
111+
| data | object | event data | In responses from the server |
112+
| args | object | command arguments | In commands sent to the server |
113+
64114
## Authenticating
65115

66116
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](/developers/topics/rpc#authorize):
@@ -105,7 +155,7 @@ Commands are requests made to the RPC socket by a client.
105155

106156
| Name | Description |
107157
|------------------------------------------------------------------------------|-----------------------------------------------------------------|
108-
| [DISPATCH](/developers/topics/rpc#commands-and-events-rpc-events) | event dispatch |
158+
| DISPATCH | event dispatch |
109159
| [AUTHORIZE](/developers/topics/rpc#authorize) | used to authorize a new client with your app |
110160
| [AUTHENTICATE](/developers/topics/rpc#authenticate) | used to authenticate an existing client with your app |
111161
| [GET_GUILD](/developers/topics/rpc#getguild) | used to retrieve guild information from the client |
@@ -130,28 +180,33 @@ Events are payloads sent over the socket to a client that correspond to events i
130180
<ManualAnchor id="commands-and-events-rpc-events" />
131181
###### RPC Events
132182

133-
| Name | Description |
134-
|-----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
135-
| [READY](/developers/topics/rpc#ready) | non-subscription event sent immediately after connecting, contains server information |
136-
| [ERROR](/developers/topics/rpc#error) | non-subscription event sent when there is an error, including command responses |
137-
| [GUILD_STATUS](/developers/topics/rpc#guildstatus) | sent when a subscribed server's state changes |
138-
| [GUILD_CREATE](/developers/topics/rpc#guildcreate) | sent when a guild is created/joined on the client |
139-
| [CHANNEL_CREATE](/developers/topics/rpc#channelcreate) | sent when a channel is created/joined on the client |
140-
| [VOICE_CHANNEL_SELECT](/developers/topics/rpc#voicechannelselect) | sent when the client joins a voice channel |
141-
| [VOICE_STATE_CREATE](/developers/topics/rpc#voicestatecreatevoicestateupdatevoicestatedelete) | sent when a user joins a subscribed voice channel |
142-
| [VOICE_STATE_UPDATE](/developers/topics/rpc#voicestatecreatevoicestateupdatevoicestatedelete) | sent when a user's voice state changes in a subscribed voice channel (mute, volume, etc.) |
143-
| [VOICE_STATE_DELETE](/developers/topics/rpc#voicestatecreatevoicestateupdatevoicestatedelete) | sent when a user parts a subscribed voice channel |
144-
| [VOICE_SETTINGS_UPDATE](/developers/topics/rpc#voicesettingsupdate) | sent when the client's voice settings update |
145-
| [VOICE_CONNECTION_STATUS](/developers/topics/rpc#voiceconnectionstatus) | sent when the client's voice connection status changes |
146-
| [SPEAKING_START](/developers/topics/rpc#speakingstartspeakingstop) | sent when a user in a subscribed voice channel speaks |
147-
| [SPEAKING_STOP](/developers/topics/rpc#speakingstartspeakingstop) | sent when a user in a subscribed voice channel stops speaking |
148-
| [MESSAGE_CREATE](/developers/topics/rpc#messagecreatemessageupdatemessagedelete) | sent when a message is created in a subscribed text channel |
149-
| [MESSAGE_UPDATE](/developers/topics/rpc#messagecreatemessageupdatemessagedelete) | sent when a message is updated in a subscribed text channel |
150-
| [MESSAGE_DELETE](/developers/topics/rpc#messagecreatemessageupdatemessagedelete) | sent when a message is deleted in a subscribed text channel |
151-
| [NOTIFICATION_CREATE](/developers/topics/rpc#notificationcreate) | sent when the client receives a notification (mention or new message in eligible channels) |
152-
| [ACTIVITY_JOIN](/developers/topics/rpc#activityjoin) | sent when the user clicks a Rich Presence join invite in chat to join a game |
153-
| [ACTIVITY_SPECTATE](/developers/topics/rpc#activityspectate) | sent when the user clicks a Rich Presence spectate invite in chat to spectate a game |
154-
| [ACTIVITY_JOIN_REQUEST](/developers/topics/rpc#activityjoinrequest) | sent when the user receives a Rich Presence Ask to Join request |
183+
| Name | Description |
184+
|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
185+
| [READY](/developers/topics/rpc#ready-ready-dispatch-data-structure) | non-subscription event sent immediately after connecting, contains server information |
186+
| [ERROR](/developers/topics/rpc#error-error-data-structure) | non-subscription event sent when there is an error, including command responses |
187+
| CURRENT_USER_UPDATE | sent when the local user's data (avatar, username, etc.) changes |
188+
| RELATIONSHIP_UPDATE | sent when a relationship (friend, block, etc.) is added or removed |
189+
| [GUILD_STATUS](/developers/topics/rpc#guildstatus) | sent when a subscribed server's state changes |
190+
| [GUILD_CREATE](/developers/topics/rpc#guildcreate) | sent when a guild is created/joined on the client |
191+
| [CHANNEL_CREATE](/developers/topics/rpc#channelcreate) | sent when a channel is created/joined on the client |
192+
| [VOICE_CHANNEL_SELECT](/developers/topics/rpc#voicechannelselect) | sent when the client joins a voice channel |
193+
| [VOICE_STATE_CREATE](/developers/topics/rpc#voicestatecreate/voicestateupdate/voicestatedelete) | sent when a user joins a subscribed voice channel |
194+
| [VOICE_STATE_UPDATE](/developers/topics/rpc#voicestatecreate/voicestateupdate/voicestatedelete) | sent when a user's voice state changes in a subscribed voice channel (mute, volume, etc.) |
195+
| [VOICE_STATE_DELETE](/developers/topics/rpc#voicestatecreate/voicestateupdate/voicestatedelete) | sent when a user parts a subscribed voice channel |
196+
| [VOICE_SETTINGS_UPDATE](/developers/topics/rpc#voicesettingsupdate) | sent when the client's voice settings update |
197+
| [VOICE_CONNECTION_STATUS](/developers/topics/rpc#voiceconnectionstatus) | sent when the client's voice connection status changes |
198+
| [SPEAKING_START](/developers/topics/rpc#speakingstart/speakingstop) | sent when a user in a subscribed voice channel speaks |
199+
| [SPEAKING_STOP](/developers/topics/rpc#speakingstart/speakingstop) | sent when a user in a subscribed voice channel stops speaking |
200+
| [MESSAGE_CREATE](/developers/topics/rpc#messagecreate/messageupdate/messagedelete) | sent when a message is created in a subscribed text channel |
201+
| [MESSAGE_UPDATE](/developers/topics/rpc#messagecreate/messageupdate/messagedelete) | sent when a message is updated in a subscribed text channel |
202+
| [MESSAGE_DELETE](/developers/topics/rpc#messagecreate/messageupdate/messagedelete) | sent when a message is deleted in a subscribed text channel |
203+
| [NOTIFICATION_CREATE](/developers/topics/rpc#notificationcreate) | sent when the client receives a notification (mention or new message in eligible channels) |
204+
| [ACTIVITY_JOIN](/developers/topics/rpc#activityjoin) | sent when the user clicks a Rich Presence join invite in chat to join a game |
205+
| [ACTIVITY_SPECTATE](/developers/topics/rpc#activityspectate) | sent when the user clicks a Rich Presence spectate invite in chat to spectate a game |
206+
| [ACTIVITY_JOIN_REQUEST](/developers/topics/rpc#activityjoinrequest) | sent when the user receives a Rich Presence Ask to Join request |
207+
| ACTIVITY_INVITE | sent when the user receives an activity invitation |
208+
| ENTITLEMENT_CREATE | sent when a user purchases or receives a new entitlement (SKU/Game) |
209+
| ENTITLEMENT_DELETE | sent when an entitlement is removed |
155210

156211
#### AUTHORIZE
157212

0 commit comments

Comments
 (0)