Skip to content

Commit 51c9646

Browse files
markmandelmarkmandel
committed
docs(rpc): add reference documentation for new IPC events
Add anchor links and full dispatch data structure documentation for ACTIVITY_INVITE, CURRENT_USER_UPDATE, RELATIONSHIP_UPDATE, ENTITLEMENT_CREATE, and ENTITLEMENT_DELETE, which were added to the RPC Events table without reference sections. Also did some minor cleanup of text, and linked to the Social SDK. Continuation of work in #8246
1 parent 86d1f28 commit 51c9646

1 file changed

Lines changed: 258 additions & 7 deletions

File tree

‎developers/topics/rpc.mdx‎

Lines changed: 258 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,11 @@ import {ManualAnchor} from '/snippets/manualanchor.jsx'
88

99
## RPC over IPC
1010

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.
11+
Discord's RPC server supports IPC (Inter-Process Communication) as transport for native applications and games. This allows high-performance, local communication with the Discord client without requiring network-level overhead.
12+
13+
<Warning>
14+
We recommend using the [Discord Social SDK](/developers/discord-social-sdk/overview) for new projects that are looking to integrate Discord's social features into their game.
15+
</Warning>
1216

1317
###### IPC Path
1418

@@ -113,7 +117,7 @@ For applications/games not approved, we limit you to creating 10 guilds and 10 c
113117

114118
## Authenticating
115119

116-
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):
120+
In order to call any commands over RPC, you must be authenticated or you will receive a code `4006` error response. To begin, call [AUTHORIZE](/developers/topics/rpc#authorize):
117121

118122
<ManualAnchor id="authenticating-rpc-authorize-example" />
119123
###### RPC Authorize Example
@@ -184,8 +188,8 @@ Events are payloads sent over the socket to a client that correspond to events i
184188
|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
185189
| [READY](/developers/topics/rpc#ready-ready-dispatch-data-structure) | non-subscription event sent immediately after connecting, contains server information |
186190
| [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 |
191+
| [CURRENT_USER_UPDATE](/developers/topics/rpc#currentuserupdate) | sent when the local user's data (avatar, username, etc.) changes |
192+
| [RELATIONSHIP_UPDATE](/developers/topics/rpc#relationshipupdate) | sent when a relationship (friend, block, etc.) is added or removed |
189193
| [GUILD_STATUS](/developers/topics/rpc#guildstatus) | sent when a subscribed server's state changes |
190194
| [GUILD_CREATE](/developers/topics/rpc#guildcreate) | sent when a guild is created/joined on the client |
191195
| [CHANNEL_CREATE](/developers/topics/rpc#channelcreate) | sent when a channel is created/joined on the client |
@@ -204,9 +208,9 @@ Events are payloads sent over the socket to a client that correspond to events i
204208
| [ACTIVITY_JOIN](/developers/topics/rpc#activityjoin) | sent when the user clicks a Rich Presence join invite in chat to join a game |
205209
| [ACTIVITY_SPECTATE](/developers/topics/rpc#activityspectate) | sent when the user clicks a Rich Presence spectate invite in chat to spectate a game |
206210
| [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 |
211+
| [ACTIVITY_INVITE](/developers/topics/rpc#activityinvite) | sent when the user receives an activity invitation |
212+
| [ENTITLEMENT_CREATE](/developers/topics/rpc#entitlementcreate) | sent when a user purchases or receives a new entitlement (SKU/Game) |
213+
| [ENTITLEMENT_DELETE](/developers/topics/rpc#entitlementdelete) | sent when an entitlement is removed |
210214

211215
#### AUTHORIZE
212216

@@ -1787,3 +1791,250 @@ No arguments
17871791
"evt": "ACTIVITY_JOIN_REQUEST"
17881792
}
17891793
```
1794+
1795+
<ManualAnchor id="activityinvite" />
1796+
#### ACTIVITY_INVITE
1797+
1798+
No arguments
1799+
1800+
<ManualAnchor id="activityinvite-activity-invite-dispatch-data-structure" />
1801+
###### Activity Invite Dispatch Data Structure
1802+
1803+
| Field | Type | Description |
1804+
|------------|----------------------------------------------------------------------|------------------------------------------|
1805+
| type | integer | invite type; `1` for join |
1806+
| user | partial [user](/developers/resources/user#user-object) object | user who sent the invite |
1807+
| activity | [activity](/developers/events/gateway-events#activity-object) object | the activity associated with the invite |
1808+
| channel_id | string | id of the channel the invite was sent in |
1809+
| message_id | string | id of the invite message |
1810+
1811+
<ManualAnchor id="activityinvite-example-activity-invite-dispatch-payload" />
1812+
###### Example Activity Invite Dispatch Payload
1813+
1814+
```json
1815+
{
1816+
"cmd": "DISPATCH",
1817+
"data": {
1818+
"type": 1,
1819+
"user": {
1820+
"id": "53908232506183680",
1821+
"username": "Mason",
1822+
"discriminator": "1337",
1823+
"avatar": "a_bab14f271d565501444b2ca3be944b25"
1824+
},
1825+
"activity": {
1826+
"application_id": "192741864418312192",
1827+
"name": "My Game",
1828+
"party": {
1829+
"id": "party1234",
1830+
"size": [2, 5]
1831+
}
1832+
},
1833+
"channel_id": "199737254929760256",
1834+
"message_id": "199743874640379904"
1835+
},
1836+
"evt": "ACTIVITY_INVITE"
1837+
}
1838+
```
1839+
1840+
<ManualAnchor id="currentuserupdate" />
1841+
#### CURRENT_USER_UPDATE
1842+
1843+
No arguments. Dispatches the current user's profile whenever it changes (avatar, username, etc.).
1844+
1845+
<ManualAnchor id="currentuserupdate-current-user-update-dispatch-data-structure" />
1846+
###### Current User Update Dispatch Data Structure
1847+
1848+
| Field | Type | Description |
1849+
|------------------------|---------|-------------------------------------------------------------------------------------------|
1850+
| id | string | user's id |
1851+
| username | string | user's username |
1852+
| discriminator | string | user's discriminator |
1853+
| global_name | string | user's display name |
1854+
| avatar | string | user's avatar hash |
1855+
| avatar_decoration_data | object | avatar decoration data, if any (`null` if none) |
1856+
| bot | boolean | whether the user is a bot |
1857+
| flags | integer | the public [flags](/developers/resources/user#user-object-user-flags) on a user's account |
1858+
| premium_type | integer | type of [Nitro subscription](/developers/resources/user#user-object-premium-types) |
1859+
1860+
<ManualAnchor id="currentuserupdate-example-current-user-update-dispatch-payload" />
1861+
###### Example Current User Update Dispatch Payload
1862+
1863+
```json
1864+
{
1865+
"cmd": "DISPATCH",
1866+
"data": {
1867+
"id": "53908232506183680",
1868+
"username": "Mason",
1869+
"discriminator": "0",
1870+
"global_name": "Mason",
1871+
"avatar": "a_bab14f271d565501444b2ca3be944b25",
1872+
"avatar_decoration_data": null,
1873+
"bot": false,
1874+
"flags": 64,
1875+
"premium_type": 2
1876+
},
1877+
"evt": "CURRENT_USER_UPDATE"
1878+
}
1879+
```
1880+
1881+
<ManualAnchor id="relationshipupdate" />
1882+
#### RELATIONSHIP_UPDATE
1883+
1884+
No arguments. Requires the `relationships_read` [OAuth2 scope](/developers/topics/oauth2#shared-resources-oauth2-scopes).
1885+
1886+
Fired when a relationship is added, updated (e.g. presence change), or removed. When a relationship is removed, `type` will be `0` (`NONE`).
1887+
1888+
<ManualAnchor id="relationshipupdate-relationship-update-dispatch-data-structure" />
1889+
###### Relationship Update Dispatch Data Structure
1890+
1891+
| Field | Type | Description |
1892+
|----------|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
1893+
| type | integer | [relationship type](/developers/topics/rpc#relationshipupdate-relationship-types) |
1894+
| user | partial [user](/developers/resources/user#user-object) object | the related user |
1895+
| presence | [presence](/developers/topics/rpc#relationshipupdate-presence-object) object | the related user's current presence |
1896+
1897+
<ManualAnchor id="relationshipupdate-relationship-types" />
1898+
###### Relationship Types
1899+
1900+
| Type | Value | Description |
1901+
|------------------|-------|------------------------------------------|
1902+
| NONE | 0 | relationship removed |
1903+
| FRIEND | 1 | user is a friend |
1904+
| BLOCKED | 2 | user is blocked |
1905+
| PENDING_INCOMING | 3 | incoming friend request |
1906+
| PENDING_OUTGOING | 4 | outgoing friend request |
1907+
| IMPLICIT | 5 | user is in a mutual guild (not a friend) |
1908+
1909+
<ManualAnchor id="relationshipupdate-presence-object" />
1910+
###### Presence Object
1911+
1912+
| Field | Type | Description |
1913+
|----------|----------------------------------------------------------------------|---------------------------------------------------------------|
1914+
| status | string | user's status (`online`, `idle`, `dnd`, `offline`) |
1915+
| activity | [activity](/developers/events/gateway-events#activity-object) object | user's current activity for this application (`null` if none) |
1916+
1917+
<ManualAnchor id="relationshipupdate-example-relationship-update-dispatch-payload" />
1918+
###### Example Relationship Update Dispatch Payload
1919+
1920+
```json
1921+
{
1922+
"cmd": "DISPATCH",
1923+
"data": {
1924+
"type": 1,
1925+
"user": {
1926+
"id": "190320984123768832",
1927+
"username": "test user 2",
1928+
"discriminator": "0",
1929+
"global_name": "test user 2",
1930+
"avatar": "b004ec1740a63ca06ae2e14c5cee11f3",
1931+
"bot": false,
1932+
"flags": 0,
1933+
"premium_type": 0
1934+
},
1935+
"presence": {
1936+
"status": "online",
1937+
"activity": null
1938+
}
1939+
},
1940+
"evt": "RELATIONSHIP_UPDATE"
1941+
}
1942+
```
1943+
1944+
<ManualAnchor id="entitlementcreate" />
1945+
#### ENTITLEMENT_CREATE
1946+
1947+
No arguments. Fired when the user acquires a new entitlement for this application.
1948+
1949+
<ManualAnchor id="entitlementcreate-entitlement-create-dispatch-data-structure" />
1950+
###### Entitlement Create Dispatch Data Structure
1951+
1952+
| Field | Type | Description |
1953+
|-------------|-----------------------------------------------------------------------------------|----------------------------------|
1954+
| entitlement | [entitlement](/developers/topics/rpc#entitlementcreate-entitlement-object) object | the entitlement that was created |
1955+
1956+
<ManualAnchor id="entitlementcreate-entitlement-object" />
1957+
###### Entitlement Object
1958+
1959+
| Field | Type | Description |
1960+
|----------------|---------|--------------------------------------------------------------------------------|
1961+
| id | string | entitlement id |
1962+
| sku_id | string | id of the SKU this entitlement is for |
1963+
| application_id | string | id of the application |
1964+
| user_id | string | id of the user that owns the entitlement |
1965+
| type | integer | [entitlement type](/developers/topics/rpc#entitlementcreate-entitlement-types) |
1966+
| deleted | boolean | whether the entitlement has been deleted |
1967+
| starts_at? | ISO8601 | start date of the entitlement |
1968+
| ends_at? | ISO8601 | end date of the entitlement |
1969+
| guild_id? | string | id of the guild the entitlement applies to |
1970+
| consumed? | boolean | for consumable entitlements, whether the entitlement has been consumed |
1971+
1972+
<ManualAnchor id="entitlementcreate-entitlement-types" />
1973+
###### Entitlement Types
1974+
1975+
| Type | Value | Description |
1976+
|--------------------------|-------|--------------------------------|
1977+
| PURCHASE | 1 | purchased by a user |
1978+
| PREMIUM_SUBSCRIPTION | 2 | a Nitro subscription |
1979+
| DEVELOPER_GIFT | 3 | gifted by a developer |
1980+
| TEST_MODE_PURCHASE | 4 | purchased in test mode |
1981+
| FREE_PURCHASE | 5 | granted for free |
1982+
| USER_GIFT | 6 | gifted by another user |
1983+
| PREMIUM_PURCHASE | 7 | purchased as a premium feature |
1984+
| APPLICATION_SUBSCRIPTION | 8 | an app subscription |
1985+
1986+
<ManualAnchor id="entitlementcreate-example-entitlement-create-dispatch-payload" />
1987+
###### Example Entitlement Create Dispatch Payload
1988+
1989+
```json
1990+
{
1991+
"cmd": "DISPATCH",
1992+
"data": {
1993+
"entitlement": {
1994+
"id": "1019653849998299136",
1995+
"sku_id": "1019475255913222144",
1996+
"application_id": "192741864418312192",
1997+
"user_id": "53908232506183680",
1998+
"type": 8,
1999+
"deleted": false,
2000+
"starts_at": "2022-09-14T17:00:18.704163+00:00",
2001+
"ends_at": "2022-10-14T17:00:18.704163+00:00"
2002+
}
2003+
},
2004+
"evt": "ENTITLEMENT_CREATE"
2005+
}
2006+
```
2007+
2008+
<ManualAnchor id="entitlementdelete" />
2009+
#### ENTITLEMENT_DELETE
2010+
2011+
No arguments. Fired when an entitlement for this application is removed. The entitlement object in the payload reflects the state of the entitlement at the time of deletion.
2012+
2013+
<ManualAnchor id="entitlementdelete-entitlement-delete-dispatch-data-structure" />
2014+
###### Entitlement Delete Dispatch Data Structure
2015+
2016+
| Field | Type | Description |
2017+
|-------------|-----------------------------------------------------------------------------------|----------------------------------|
2018+
| entitlement | [entitlement](/developers/topics/rpc#entitlementcreate-entitlement-object) object | the entitlement that was deleted |
2019+
2020+
<ManualAnchor id="entitlementdelete-example-entitlement-delete-dispatch-payload" />
2021+
###### Example Entitlement Delete Dispatch Payload
2022+
2023+
```json
2024+
{
2025+
"cmd": "DISPATCH",
2026+
"data": {
2027+
"entitlement": {
2028+
"id": "1019653849998299136",
2029+
"sku_id": "1019475255913222144",
2030+
"application_id": "192741864418312192",
2031+
"user_id": "53908232506183680",
2032+
"type": 8,
2033+
"deleted": true,
2034+
"starts_at": "2022-09-14T17:00:18.704163+00:00",
2035+
"ends_at": "2022-10-14T17:00:18.704163+00:00"
2036+
}
2037+
},
2038+
"evt": "ENTITLEMENT_DELETE"
2039+
}
2040+
```

0 commit comments

Comments
 (0)