A user's presence is their current status and activity. Presences are usually per-guild, but user accounts also receive overall user presences for friends and implicit relationships (depending on the Gateway capability ).
Field Type Description user partial user object The user whose presence is being updated guild_id? snowflake ID of the guild the presence was updated in, if this is a guild presence status string The status of the user activities array[activity object] The current activities the user is partaking in client_status client status objectThe platform-dependent status of the user
Represents a specific Gateway session's presence information for the current user.
In cases of ambiguity, e.g. when the user has multiple sessions with an active presence, a special session with a value of
will exist to represent the user's overall presence. This will be the presence that is broadcasted to other users.
The overall presence will always have unknown values for .
Field Type Description session_id 1 string The ID of the session client_info client info objectInformation about the client that spawned the session status string The status of the session activities array[activity object] The current activities the session is partaking in active? boolean Unknown
1 Headless sessions will have a session ID beginning with .
Field Type Description client string The type of client os string The operating system of the client version integer The version of the client type (e.g. for the PS5)
Value Description desktop Desktop client web Web-based client mobile Mobile client unknown Unknown
Value Description windows Windows osx macOS linux Linux android Android ios iOS playstation PlayStation unknown Unknown
Active sessions are indicated with a status per platform. If a user is offline or invisible, the corresponding field is not present.
Field Type Description desktop? string The user's status on an active desktop (Windows, Linux, Mac) application session mobile? string The user's status on an active mobile (iOS, Android) application session web? 1 string The user's status on an active web (browser) application session embedded? string The user's status on an active embedded (Xbox, PlayStation) session
1 Used as the default when the platform is not known.
Value Description online Online dnd Do Not Disturb idle AFK invisible 1 Shown as offline offline 1 Offline unknown 2 Unknown
1 can only be sent and never received. can only be received and never sent.
2 This value can only be sent, and is used when the user's initial presence is unknown and should be assigned by the Gateway.
Field Type Description id 5 string The ID of the activity; only unique across a single user's activities name 1 string The name of the activity (2-128 characters) type integer The activity type url? 2 ?string The stream URL (max 512 characters) created_at 5 integer Unix timestamp (in milliseconds) of when the activity was added to the user's session session_id? 5 ?string The ID of the session associated with the activity platform? 3 string The platform the activity is being played on supported_platforms? array[string] The platforms the activity is supported on timestamps? activity timestamps objectUnix timestamps (in milliseconds) for start and/or end of the game application_id? snowflake The ID of the application representing the game the user is playing details? ?string What the user is currently doing (max 128 characters) state? ?string The user's current party status (max 128 characters) sync_id? string The ID of the synced activity (e.g. Spotify song ID) flags? integer The activity's flags buttons? array[string] Custom buttons shown in rich presence (max 2) emoji? ?activity emoji object The emoji used for a custom status party? activity party objectInformation for the current party of the user assets? activity assets objectImages for the presence and their hover texts secrets? 4 activity secrets objectSecrets for rich presence joining and spectating metadata? 4 activity metadata objectAdditional metadata for the activity
1 The of a activity should always be "Custom Status".
2 URLs must start with or .
3 This field is not commonly used for traditional presences (i.e. presences sent by regular clients over the Gateway) and is instead used to differentiate between various headless and embedded activities.
4 These fields are send-only. For retrieving rich presence metadata, see Get Activity Metadata . For retrieving secrets, see Get Activity Secret .
5 These fields are received only and cannot be set.
Bots are only able to send , , , and optionally .
Value Name Format Example 0 PLAYING Playing {name} "Playing Rocket League" 1 STREAMING Streaming {details} "Streaming Rocket League" 2 LISTENING Listening to {name} "Listening to Spotify" 3 WATCHING Watching {name} "Watching YouTube Together" 4 CUSTOM {emoji} {state} "😃 I am cool" 5 COMPETING Competing in {name} "Competing in Arena World Champions" 6HANG{state} or {emoji} {details}"Chilling"
Value Description desktop Desktop (headless) xbox Xbox integration samsung Samsung integration ios iOS android Android embedded Embedded session ps4 PlayStation 4 integration ps5 PlayStation 5 integration
Value Name Description 1 << 0 INSTANCE This activity is an instanced game session (a match that will end) 1 << 1 JOIN This activity can be joined by other users 1 << 2 SPECTATE (deprecated) 1 This activity can be spectated by other users 1 << 3JOIN_REQUEST 2 This activity requires a request to join1 << 4 SYNC This activity can be synced 1 << 5 PLAY This activity can be played 1 << 6 PARTY_PRIVACY_FRIENDS This activity's party can be joined by friends 1 << 7 PARTY_PRIVACY_VOICE_CHANNEL This activity's party can be joined by users in the same voice channel 1 << 8 EMBEDDED This activity is embedded within the Discord client
1 Spectating has been removed from official clients and is no longer supported.
2 Activities no longer need to be explicitly flagged as join requestable.
Value Name Description 1 JOIN 1 Allows others to join a game with the user 2 SPECTATE (deprecated) 1 2 Allows others to spectate a game the user is playing 3 LISTEN Allows others to listen to a song with the user 4WATCHAllows others to join a stream with the user5 JOIN_REQUEST 3 Asks others to invite the user to a game
1 These rich presence invites can be used with the Get Activity Secret endpoint to join/spectate the activity.
2 Spectating has been removed from official clients and is no longer supported.
3 This action type is special in that instead of inviting others to a party, it asks existing party members to invite the user to join their party. Inviting users is done by sending a message back with a rich presence invite .
Field Type Description start? string Unix time (in milliseconds) of when the activity starts end? string Unix time (in milliseconds) of when the activity ends
Field Type Description name string The name of the emoji id? snowflake The ID of the emoji animated? boolean Whether this emoji is animated
Field Type Description id? string The ID of the party (max 128 characters) size? array[integer, integer] The party's current and maximum size (current_size, max_size)
Field Type Description large_image? string The large activity asset image (max 313 characters) large_text? string Text displayed when hovering over the large image of the activity (max 128 characters) small_image? string The small activity asset image (max 313 characters) small_text? string Text displayed when hovering over the small image of the activity (max 128 characters)
Activity asset images are arbitrary strings which usually contain snowflake IDs or prefixed image IDs. Treat data within this field carefully, as it is user-specifiable and not sanitized.
To use an external image via media proxy, specify the URL as the field's value when sending. You will only receive the -prefixed value via the Gateway.
Field Type Description join? string The secret for joining a party (max 128 characters) spectate? (deprecated) 1 string The secret for spectating a game (max 128 characters) match?stringThe secret for a specific instanced match (max 128 characters)
1 Spectating has been removed from official clients and is no longer supported.
Value Description win32 Windows darwin macOS linux Linux
{
"id" : "d11307d8c0abb136" ,
"created_at" : "1695164784863" ,
"details" : "24H RL Stream for Charity" ,
"state" : "Rocket League" ,
"name" : "Twitch" ,
"type" : 1 ,
"url" : "https://www.twitch.tv/discord" ,
"assets" : {
"large_image" : "twitch:discord"
}
}
{
"id" : "d11307d8c0abb135" ,
"name" : "Rocket League" ,
"type" : 0 ,
"created_at" : "1695164784863" ,
"session_id" : "30f32c5d54ae86130fc4a215c7474263" ,
"application_id" : "379286085710381999" ,
"state" : "In a Match" ,
"details" : "Ranked Duos: 2-1" ,
"platform" : "xbox" ,
"flags" : 0 ,
"timestamps" : {
"start" : "1695164482423"
} ,
"party" : {
"id" : "9dd6594e-81b3-49f6-a6b5-a679e6a060d3" ,
"size" : [ 2 , 2 ]
} ,
"assets" : {
"large_image" : "351371005538729000" ,
"large_text" : "DFH Stadium" ,
"small_image" : "351371005538729111" ,
"small_text" : "Silver III"
} ,
"secrets" : {
"join" : "025ed05c71f639de8bfaa0d679d7c94b2fdce12f"
}
}
Activity metadata can consist of arbitrary data, and is not sanitized by the API. Treat data within this object carefully.
The below structure is only a convention that is used by official clients. It is not enforced by the API.
Field Type Description button_urls? array[string] The URLs corresponding to the custom buttons shown in rich presence (max 2) artist_ids? array[string] The Spotify IDs of the artists of the song being played album_id? string The Spotify ID of the album of the song being played context_uri? string The Spotify URI of the current player context type? string The type of Spotify track being played ( or )
GET/presences
Returns the overall user presence for all of the user's non-offline friends and implicit relationships .
Field Type Description presences array[presence object] The overall user presences of the user's non-offline friends and implicit relationships applications array[partial application object] The found game applications in the presences
POST/presences
Updates the current user's mobile game activity. Returns a 204 empty response on success. Fires a Sessions Replace Gateway event.
This endpoint is meant to be used by the Samsung Game launcher only. Because of this, all activities created through it will appear as an Android mobile session, and the activity platform will always be .
For OAuth2 requests, this endpoint is locked to the Samsung Game Launcher application ID ().
If the application for the game you are trying to play is not yet cached, the endpoint will return a 202 accepted response. The response body will look similar to an error response:
{ "message" : "Application not yet available. Try again later" , "code" : 110001 , "retry_after" : 4000 }
You should retry the request after the timeframe specified in the field. If the field is , you should retry the request after a short delay.
See the unavailable resources section for more information.
Field Type Description package_name string The package name of the game (e.g. ) update? string The type of update (default )
Value Description START Start a new game session UPDATE Update the current game session STOP Stop the current game session
GET/activities
Returns a list of global activity statistics objects representing games the user's friends and affine users have recently played.
Field Type Description user_id string The ID of the user playing the game application_id string The ID of the application representing the game updated_at ISO8601 timestamp When the user last played the game duration integer How long the user played the game for (in seconds)
{
"user_id" : "1001086404203389018" ,
"application_id" : "1334568856227942480" ,
"updated_at" : "2025-03-01T14:58:02.284000+00:00" ,
"duration" : 1176
}
GET/activities/statistics/applications/{application.id}
Returns a list of application activity statistics objects representing the user's friends and affine users that have played the given game.
Field Type Description user_id string The ID of the user playing the game last_played_at ISO8601 timestamp When the user last played the game total_duration integer How long the user has ever played the game for (in seconds)
{
"user_id" : "343383572805058560" ,
"last_played_at" : "2025-02-20T00:21:07.457000+00:00" ,
"total_duration" : 1180625
}
GET/users/@me/activities/statistics/applications
Returns a list of user application activity statistics objects representing games the user has played.
Field Type Description application_id string The ID of the application representing the game last_played_at ISO8601 timestamp When the user last played the game first_played_at ?ISO8601 timestamp When the user first played the game (may not be tracked) total_duration integer How long the user has ever played the game for (in seconds) total_discord_sku_duration integer How long the user has ever played the game through Discord (in seconds)
{
"application_id" : "356875221078245376" ,
"last_played_at" : "2025-02-20T06:24:34.792000+00:00" ,
"first_played_at" : "2024-04-29T22:23:30.307000+00:00" ,
"total_duration" : 246531 ,
"total_discord_sku_duration" : 0
}
POST/activities
Updates a currently running activity game session for the current user.
Field Type Description token? string The token of the existing session to update application_id snowflake The ID of the application representing the game duration? integer How long the game has been played for (in seconds) sine the last update (max 1800) share_activity? boolean Whether to share the activity in activity statistics (default true) distributor? string The distributor of the game exe_path? string The path to the game's executable file (max 128 characters) voice_channel_id? snowflake The ID of the voice channel the user is in while playing the game session_id? string The ID of the session associated with the activity media_session_id? string The ID of the voice connection media session associated with the activity closed? boolean Whether the game has been closed and the session is over (default false)
Field Type Description token string The updated token of the session
{
"token" : ".eJxNzEEKwyAUBNCrBLdtyqjx6_cc3YvELKShCYmuSu_eWArNcoY38xJ1n7aQk_CdcEY5VootkWQQsxbXTsR1nfMYS16ePyclazkQEzslodXA3GBdUyxTCrE0pKBMD92D7rAezht7I2tAdAE80Bapbt_fw-OIZSlxDqdS2uFf531cthT2Rz0TvD_X3TcU.Z8lKCQ.QvSLefzqmY6lhaBaQNG308fl3e8"
}
POST/users/@me/headless-sessions
Creates a new headless session for the current user. Fires a Sessions Replace Gateway event.
Field Type Description activities 1 array[activity object] An array containing exactly one activity to set for the headless session token? string The token of the headless session to update
1 In addition to and , this activity object must also have a valid and set.
Field Type Description activities array[activity object] The current activities the headless session is partaking in token string The token of the headless session
POST/users/@me/headless-sessions/delete
Deletes a headless session for the current user. Returns a 204 empty response on success. Fires a Sessions Replace Gateway event.
Field Type Description token string The token of the headless session
GET/users/{user.id}/sessions/{session_id}/activities/{application.id}/metadata
Returns the activity metadata for a given activity, or a 204 empty response if no metadata is found.
A special of can be used to retrieve the metadata for the user's primary activity if it does not have an set.
GET/users/{user.id}/sessions/{session_id}/activities/{application.id}/{activity_action_type}
Returns an activity secret that can be used to join or spectate the game. Only supports the and action types .
If a rich presence invite is not specified in the query string, the activity must have the or
activity flag set, and the user must meet the flag requirements.
Field Type Description channel_id? snowflake The ID of the channel the rich presence invite has been sent in message_id? snowflake The ID of the rich presence invite message
Field Type Description secret string The activity secret
{ "secret" : "025ed05c71f639de8bfaa0d679d7c94b2fdce12f" }