Presence Resource

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

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 object	The platform-dependent status of the user

Status Type

Value	Description
online	Online
dnd	Do Not Disturb
idle	AFK
invisible ¹	Shown as offline
offline ¹	Offline
unknown ²	Unknown

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

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.

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? ¹	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

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

Activity Object

Activity Structure

Field	Type	Description
id	string	The ID of the activity; only unique across a single user's activities
name ¹	string	The name of the activity
type	integer	The activity type
url? ²	?string	The stream URL
created_at	integer	Unix timestamp (in milliseconds) of when the activity was added to the user's session
session_id?	?string	The ID of the session associated with the activity
platform? ³	string	The platform the activity is being played on
supported_platforms?	array[string]	The platforms the activity is supported on
timestamps?	activity timestamps object	Unix 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
state? ⁴	?string	The user's current party status
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/hang status
party?	activity party object	Information for the current party of the user
assets?	activity assets object	Images for the presence and their hover texts
secrets? ⁵	activity secrets object	Secrets for rich presence joining and spectating
metadata? ⁵	activity metadata object	Additional metadata for the activity

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

² The STREAMING type currently only supports Twitch and YouTube. Only https://twitch.tv/ and https://youtube.com/ URLs will work.

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

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

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

Activity Type

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"
6	HANG ¹	{state} or {emoji} {details} ²	"Chilling"

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

² See activity hang status type for more information.

Activity Platform Type

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

Activity Hang Status Type

When a HANG activity's state is set to one of these values, a built-in corresponding emoji will be used instead of the custom emoji field.

Value	Example
chilling	Chilling
gaming	GAMING
focusing	In the zone
brb	Gonna BRB
eating	Grubbin
in-transit	Wandering IRL
watching	Watchin' stuff
custom	{details}

Activity Flags

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) ¹	This activity can be spectated by other users
~~1 << 3~~	~~JOIN_REQUEST~~ ²	~~This activity requires a request to join~~
1 << 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

¹ 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

Value	Name	Description
1	JOIN ¹	Allows others to join a game with the user
2	SPECTATE (deprecated) ¹ ²	Allows others to spectate a game the user is playing
3	LISTEN	Allows others to listen to a song with the user
4	~~WATCH~~	~~Allows others to join a stream with the user~~
5	JOIN_REQUEST ³	Asks others to invite the user to a game

¹ 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

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

Activity Emoji Structure

Field	Type	Description
name	string	The name of the emoji
id?	snowflake	The ID of the emoji
animated?	boolean	Whether this emoji is animated

Activity Party Structure

Field	Type	Description
id?	string	The ID of the party
size?	array[integer, integer]	The party's current and maximum size (current_size, max_size)

Activity Assets Structure

Field	Type	Description
large_image?	string	The large activity asset image
large_text?	string	Text displayed when hovering over the large image of the activity
small_image?	string	The small activity asset image
small_text?	string	Text displayed when hovering over the small image of the activity

Activity Asset Image

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 mp:-prefixed value via the Gateway.

Type	Format	Image URL
Application Asset	`{application_asset_id}`	See application asset image formatting
Media Proxy	`mp:{image_id}`	`https://media.discordapp.net/{image_id}`
Twitch	`twitch:{username}`	`https://static-cdn.jtvnw.net/previews-ttv/live_user_{username}-{width}x{height}.jpg`
YouTube	`youtube:{video_id}`	`https://i.ytimg.com/vi/{video_id}/{thumbnail_type}.jpg`

Activity Secrets Structure

Field	Type	Description
join?	string	The secret for joining a party
spectate? (deprecated) ¹	string	The secret for spectating a game
~~match?~~	~~string~~	~~The secret for a specific instanced match~~

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

Operating System Type

Value	Description
win32	Windows
darwin	macOS
linux	Linux

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

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

Endpoints

Get Presences

GET/presences

OAuth2

Returns the overall user presence for all of the user's non-offline friends and implicit relationships.

Response Body

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

Update Presence

POST/presences

OAuth2

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

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 retry_after field. If the retry_after field is 0, you should retry the request after a short delay. See the unavailable resources section for more information.

JSON Params

Field	Type	Description
package_name	string	The package name of the game (e.g. `com.supercell.clashofclans`)
update?	string	The type of update (default `UPDATE`)

Presence Update Type

Value	Description
START	Start a new game session
UPDATE	Update the current game session
STOP	Stop the current game session

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

Response Body

Field	Type	Description
secret	string	The activity secret

Example Response

{ "secret": "025ed05c71f639de8bfaa0d679d7c94b2fdce12f" }