Skip to content

Document new rich presence url & status display type fields #7674

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Jul 17, 2025
+56 −18
Merged

Document new rich presence url & status display type fields #7674

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
84e0839
update embedded app sdk
foxfirecodes Jul 10, 2025
b0bf99e
add examples for social sdk
foxfirecodes Jul 10, 2025
dc83e2b
add to gateway events
foxfirecodes Jul 10, 2025
9c1d688
add to rpc example
foxfirecodes Jul 10, 2025
9712b88
add changelog entry
foxfirecodes Jul 10, 2025
d0cab1a
split out social sdk changes into separate pr
foxfirecodes Jul 10, 2025
be9db9b
re-add streaming disclaimer
foxfirecodes Jul 10, 2025
443d6db
clarify status text
foxfirecodes Jul 10, 2025
d143353
clarify status text in changelog too
foxfirecodes Jul 10, 2025
6616a6f
Update docs/events/gateway-events.mdx
foxfirecodes Jul 14, 2025
9680414
Update docs/change-log/2025-07-10-clickable-links-and-customizable-st…
foxfirecodes Jul 14, 2025
8817eba
update changelog
foxfirecodes Jul 17, 2025
281d90f
Update docs/change-log/2025-07-17-clickable-links-and-customizable-st…
foxfirecodes Jul 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/developer-tools/embedded-app-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1143,7 +1143,9 @@ Coming soon! Not available during Developer Preview
| timestamps? | [Timestamp](/docs/developer-tools/embedded-app-sdk#timestamp) \| null |
| application_id? | string \| null |
| details? | string \| null |
| details_url? | string \| null |
| state? | string \| null |
| state_url? | string \| null |
| emoji? | [Emoji](/docs/developer-tools/embedded-app-sdk#emoji) \| null |
| party? | [Party](/docs/developer-tools/embedded-app-sdk#party) \| null |
| assets? | [Assets](/docs/developer-tools/embedded-app-sdk#assets) \| null |
Expand All @@ -1157,8 +1159,10 @@ Coming soon! Not available during Developer Preview
|--------------|----------------|
| large_image? | string \| null |
| large_text? | string \| null |
| large_url? | string \| null |
| small_image? | string \| null |
| small_text? | string \| null |
| small_url? | string \| null |

#### Application

Expand Down
40 changes: 40 additions & 0 deletions docs/discord-social-sdk/development-guides/setting-rich-presence.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,46 @@ See the `ActivityGamePlatforms` enum for all supported platforms.

---

## Setting Field URLs

You can set URLs for `details`, `state`, `assets.large_image` and `assets.small_image` in Rich Presence. When present, these URLs will make the corresponding image/text into clickable links.

```cpp
activity.SetState("Playing on Mainframe");
activity.SetStateUrl("https://example.com/maps/mainframe");
activity.SetDetails("Rank #1337 in global leaderboard");
activity.SetDetailsUrl("https://example.com/leaderboard/global");

discordpp::ActivityAssets assets;
assets.SetLargeImage("map-mainframe");
assets.SetLargeText("Mainframe");
assets.SetLargeUrl("https://example.com/maps/mainframe");
assets.SetSmallImage("tank-avatar");
assets.SetSmallText("Tank");
assets.SetSmallUrl("https://example.com/classes/tank");

activity.SetAssets(assets);
```

---

## Configuring Status Text

By default, Rich Presence will display the game's name in the user's status text. You can override this behavior by setting a status display type.

```cpp
// uses the game's name in the status text (default)
activity.SetStatusDisplayType(discordpp::StatusDisplayTypes::Name);

// uses the activity's state field in the status text
activity.SetStatusDisplayType(discordpp::StatusDisplayTypes::State);

// uses the activity's details field in the status text
activity.SetStatusDisplayType(discordpp::StatusDisplayTypes::Details);
```

---

## Next Steps

Now that you've set up Rich Presence, you might want to explore:
Expand Down
49 changes: 31 additions & 18 deletions docs/events/gateway-events.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1133,23 +1133,26 @@ Active sessions are indicated with an "online", "idle", or "dnd" string per plat

###### Activity Structure

| Field | Type | Description |
|-----------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| name | string | Activity's name |
| type | integer | [Activity type](/docs/events/gateway-events#activity-object-activity-types) |
| url? | ?string | Stream URL, is validated when type is 1 |
| created_at | integer | Unix timestamp (in milliseconds) of when the activity was added to the user's session |
| timestamps? | [timestamps](/docs/events/gateway-events#activity-object-activity-timestamps) object | Unix timestamps for start and/or end of the game |
| application_id? | snowflake | Application ID for the game |
| details? | ?string | What the player is currently doing |
| state? | ?string | User's current party status, or text used for a custom status |
| emoji? | ?[emoji](/docs/events/gateway-events#activity-object-activity-emoji) object | Emoji used for a custom status |
| party? | [party](/docs/events/gateway-events#activity-object-activity-party) object | Information for the current party of the player |
| assets? | [assets](/docs/events/gateway-events#activity-object-activity-assets) object | Images for the presence and their hover texts |
| secrets? | [secrets](/docs/events/gateway-events#activity-object-activity-secrets) object | Secrets for Rich Presence joining and spectating |
| instance? | boolean | Whether or not the activity is an instanced game session |
| flags? | integer | [Activity flags](/docs/events/gateway-events#activity-object-activity-flags) `OR`d together, describes what the payload includes |
| buttons? | array of [buttons](/docs/events/gateway-events#activity-object-activity-buttons) | Custom buttons shown in the Rich Presence (max 2) |
| Field | Type | Description |
|----------------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| name | string | Activity's name |
| type | integer | [Activity type](/docs/events/gateway-events#activity-object-activity-types) |
| url? | ?string | Stream URL, is validated when type is 1 |
| created_at | integer | Unix timestamp (in milliseconds) of when the activity was added to the user's session |
| timestamps? | [timestamps](/docs/events/gateway-events#activity-object-activity-timestamps) object | Unix timestamps for start and/or end of the game |
| application_id? | snowflake | Application ID for the game |
| status_display_type? | ?integer | [Status display type](/docs/events/gateway-events#activity-object-status-display-types); controls which field is displayed in the user's status text |
| details? | ?string | What the player is currently doing |
| details_url? | ?string | URL that is linked when clicking on the details text |
| state? | ?string | User's current party status, or text used for a custom status |
| state_url? | ?string | URL that is linked when clicking on the state text |
| emoji? | ?[emoji](/docs/events/gateway-events#activity-object-activity-emoji) object | Emoji used for a custom status |
| party? | [party](/docs/events/gateway-events#activity-object-activity-party) object | Information for the current party of the player |
| assets? | [assets](/docs/events/gateway-events#activity-object-activity-assets) object | Images for the presence and their hover texts |
| secrets? | [secrets](/docs/events/gateway-events#activity-object-activity-secrets) object | Secrets for Rich Presence joining and spectating |
| instance? | boolean | Whether or not the activity is an instanced game session |
| flags? | integer | [Activity flags](/docs/events/gateway-events#activity-object-activity-flags) `OR`d together, describes what the payload includes |
| buttons? | array of [buttons](/docs/events/gateway-events#activity-object-activity-buttons) | Custom buttons shown in the Rich Presence (max 2) |

:::info
Bot users are only able to set `name`, `state`, `type`, and `url`.
Expand All @@ -1166,8 +1169,16 @@ Bot users are only able to set `name`, `state`, `type`, and `url`.
| 4 | Custom | `{emoji}` `{state}` | ":smiley: I am cool" |
| 5 | Competing | Competing in `{name}` | "Competing in Arena World Champions" |

###### Status Display Types

| ID | Name | Example |
|----|---------|----------------------------------------|
| 0 | Name | "Listening to Spotify" |
| 1 | State | "Listening to Rick Astley" |
| 2 | Details | "Listening to Never Gonna Give You Up" |

:::info
The streaming type currently only supports Twitch and YouTube. Only `https://twitch.tv/` and `https://youtube.com/` urls will work.
This applies to all activity types. "Listening" was used to serve as a consistent example of what the different fields might be used for.
:::

###### Activity Timestamps
Expand Down Expand Up @@ -1202,8 +1213,10 @@ For Listening and Watching activities, you can include both start and end timest
|--------------|--------|----------------------------------------------------------------------------------------------|
| large_image? | string | See [Activity Asset Image](/docs/events/gateway-events#activity-object-activity-asset-image) |
| large_text? | string | Text displayed when hovering over the large image of the activity |
| large_url? | string | URL that is linked when clicking on the large image |
| small_image? | string | See [Activity Asset Image](/docs/events/gateway-events#activity-object-activity-asset-image) |
| small_text? | string | Text displayed when hovering over the small image of the activity |
| small_url? | string | URL that is linked when clicking on the small image |

###### Activity Asset Image

Expand Down
6 changes: 5 additions & 1 deletion docs/topics/rpc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1004,16 +1004,20 @@ When using `SET_ACTIVITY`, the `activity` object is limited to a `type` of Playi
"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_text": "Pharah",
"small_url": "https://example.wiki/characters/Pharah"
},
"party": {
"id": GameEngine.GetPartyId(),
Expand Down