Skip to content

Document new rich presence url & status display type fields for Social SDK #7676

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

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+94 −19
Open

Document new rich presence url & status display type fields for Social SDK #7676

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 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
5482bab
add back social sdk changes
foxfirecodes Jul 10, 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
14 changes: 14 additions & 0 deletions ...hange-log/2025-07-10-clickable-links-and-customizable-statuses-in-activities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
title: "Clickable Links and Customizable Statuses in Activities"
date: "2025-07-10"
topics:
- "Activities"
- "Discord Social SDK"
- "Embedded App SDK"
---

We've added new functionality to Rich Presences to give users of your application a more interactive and flexible experience. There are two big changes as part of this:
- You can now add clickable links to the state text, details text, large image & small image
- You can now choose which field (name, state, or details) is used in users' status text (e.x. instead of "Listening to MyMusic" you can now have your status text show "Listening to Rick Astley")

All of these new fields are documented on the [Activity Object](/docs/events/gateway-events#activity-object) section of Gateway Events.
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