Presences

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 NO_AFFINE_USER_IDS Gateway capability).

Presence Object

Presence Structure

¹ Activities are hidden when a user is invisible or has their show_current_game privacy setting disabled. Some exceptions apply, such as the Spotify activity, which is always shown.

² To subscribe to hidden activities for a user, see the Update Activity Subscriptions endpoint.

³ Only available in OAuth2 contexts.

Session Object

Represents a specific Gateway session's presence information for the current user.

Session Structure

¹ Headless sessions will have a session ID beginning with h:.

² Activities are hidden when a user is invisible or has their show_current_game privacy setting disabled. Some exceptions apply, such as the Spotify activity, which is always shown.

Client Info Structure

Client Type

Operating System Type

Client Status Object

Active sessions are indicated with a status per platform. If a user is offline or invisible, the corresponding field is not present.

¹ Used as the default when the platform is not known.

² Only available through headless sessions

Status Type

¹ invisible can only be sent and never received. offline can only be received and never sent.

² This value can only be sent, and is used when the user's initial presence is unknown and should be assigned by the Gateway.

Activity Object

Activity Structure

¹ The name of a CUSTOM activity should always be "Custom Status". The name of a HANG activity should always be "Hang Status".

² URLs must start with http:// or https://.

³ 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.

⁴ These fields are send-only. For retrieving rich presence metadata, see Get Activity Metadata. For retrieving secrets, see Get Activity Secret.

⁵ These fields are received only and cannot be set.

⁶ When provided in a CUSTOM activity, it represents a Custom Status Label enumeration.

⁷ In the case of the HANG type, this field should be one of the hang status types. If set to custom, the details field should be used to specify the custom text, and the emoji field should be used to specify the custom emoji.

Activity Type

¹ This type is only displayed if the user has an active voice state.

² See activity hang status type for more information.

Activity Platform Type

Activity Hang Status Type

When a HANG activity's state is set to any value other than custom, a built-in corresponding emoji will be used instead of the custom emoji field.

These values may be concatenated with a colon followed by an icon variant type. The valid variants are: illocons, twemoji, and twemojimild. For example, chilling:illocons is a valid state value. The default variant is twemoji.

Activity Flags

¹ Spectating has been removed from official clients and is no longer supported.

² Activities no longer need to be explicitly flagged as join requestable.

Activity Action Type

¹ These rich presence invites can be used with the Get Activity Secret endpoint to join/spectate the activity.

² Spectating has been removed from official clients and is no longer supported.

³ 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.

Activity Timestamps Structure

Activity Emoji Structure

Activity Party Structure

Activity Assets Structure

Activity Asset Image

Activity asset images are arbitrary strings which usually contain snowflake IDs, URLs, or prefixed image IDs. Treat data within this field carefully, as it is user-specifiable and not sanitized.

Activity Secrets Structure

¹ Spectating has been removed from official clients and is no longer supported.

Operating System Type

Custom Status Label Type

Status Display Type

Example Activity

{
  "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"
  }
}

Example Activity with Rich Presence

{
  "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 Object

Activity Metadata Structure

Endpoints

Returns the overall user presence for the user's non-offline friends and implicit relationships. Only users that have an activity or are in one of the returned guilds will be included.

Response Body

Voice Guild Structure

Voice Channel Structure

¹ Only included when fetched from the Get Presences for Xbox endpoint.

Voice Stream Structure

Example Voice Guild

{
  "guild_id": "839502008108580904",
  "guild_icon": "4da69b53981d1adfa13590a3f2d856ee",
  "guild_name": "Testing Server",
  "voice_channels": [
    {
      "channel_id": "850360749460553769",
      "channel_name": "Voice",
      "users": ["150745989836308480"],
      "streams": [
        {
          "user_id": "150745989836308480"
        }
      ]
    }
  ]
}

Returns the overall user presence for the user's non-offline friends and implicit relationships, as well as their Xbox connection information. Only users that have an activity or are in one of the returned guilds will be included.

Response Body

Connected Account Structure

Updates the current user's mobile game activity. Returns a 204 empty response on success. Fires a Sessions Replace Gateway event.

JSON Params

Presence Update Type

Returns a list of global activity statistics objects representing games the user's friends and affine users have recently played.

Query String Params

Global Activity Statistics Structure

¹ Only included when with_users is set to true.

² Only included when with_applications is set to true.

Example Global Activity Statistics

{
  "user_id": "1001086404203389018",
  "application_id": "1334568856227942480",
  "updated_at": "2025-03-01T14:58:02.284000+00:00",
  "duration": 1176
}

Returns a list of application activity statistics objects representing the user's friends and affine users that have played the given game.

Application Activity Statistics Structure

Example Application Activity Statistics

{
  "user_id": "343383572805058560",
  "last_played_at": "2025-02-20T00:21:07.457000+00:00",
  "total_duration": 1180625
}

Returns a list of user application activity statistics objects representing games the user has played.

User Application Activity Statistics Structure

Example User Application Activity Statistics

{
  "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
}

Updates a currently running activity game session for the current user.

JSON Params

Response Body

Example Response

{
  "token": ".eJxNzEEKwyAUBNCrBLdtyqjx6_cc3YvELKShCYmuSu_eWArNcoY38xJ1n7aQk_CdcEY5VootkWQQsxbXTsR1nfMYS16ePyclazkQEzslodXA3GBdUyxTCrE0pKBMD92D7rAezht7I2tAdAE80Bapbt_fw-OIZSlxDqdS2uFf531cthT2Rz0TvD_X3TcU.Z8lKCQ.QvSLefzqmY6lhaBaQNG308fl3e8"
}

Creates a new headless session for the current user. Fires a Sessions Replace Gateway event.

JSON Params

¹ In addition to type and name, this activity object must also have a valid application_id and platform set.

Response Body

Deletes a headless session for the current user. Returns a 204 empty response on success. Fires a Sessions Replace Gateway event.

JSON Params

Returns the activity metadata for a given activity, or a 204 empty response if no metadata is found.

Returns an activity secret that can be used to join or spectate the game. Only supports the JOIN and SPECTATE action types.

Query String Params

Response Body

Example Response

{ "secret": "025ed05c71f639de8bfaa0d679d7c94b2fdce12f" }

Updates the current user's subscribed hidden activities. Returns a 204 empty response on success. Fires multiple Presence Update Gateway events.

JSON Params

Activity Subscription Structure