Presence()

class Presence(client_id, pipe=0, loop=None, handler=None)

Creates the Presence client ready for usage.

Parameters:

  • client_id (str) – OAuth2 App ID (found here)

  • pipe (int) – Pipe that should be used to connect to the Discord client. Defaults to 0, can be 0-9

  • loop (asyncio.BaseEventLoop) – Your own event loop (if you have one) that PyPresence should use. One will be created if not supplied. Information at https://docs.python.org/3/library/asyncio-eventloop.html

  • handler (function) – The exception handler pypresence should send asynchronous errors to. This can be a coroutine or standard function as long as it takes two arguments (exception, future). Exception will be the exception to handle and future will be an instance of asyncio.Future


connect()

Initializes the connection - must be done in order to make any updates to Rich Presence.

Return type:

pypresence.Response


clear(pid=os.getpid())

Clears the presence.

Parameters:

pid (int) – the process id of your game

Return type:

pypresence.Response


close()

Closes the connection.

Return type:

pypresence.Response


update(**options)

Sets the user’s presence on Discord.

Parameters:

  • pid (int) – the process id of your game

  • activity_type (ActivityType) – the type of activity (PLAYING, LISTENING, WATCHING, or COMPETING). See ActivityType Enum for more details. Defaults to PLAYING if not specified.

  • status_display_type (StatusDisplayType) – which field to display in the status (NAME, STATE, or DETAILS). See StatusDisplayType Enum for more details. Defaults to NAME if not specified.

  • state (str) – the user’s current status

  • state_url (str) – URL to make the state text clickable (opens when state is clicked)

  • details (str) – what the player is currently doing

  • details_url (str) – URL to make the details text clickable (opens when details is clicked)

  • name (str) – directly set what discord will display in places like the user list

  • start (int) – epoch time for game start (in seconds, will be converted to milliseconds)

  • end (int) – epoch time for game end (in seconds, will be converted to milliseconds)

  • large_image (str) – name of the uploaded image for the large profile artwork

  • large_text (str) – tooltip for the large image

  • large_url (str) – URL to make the large image clickable (opens when large image is clicked)

  • small_image (str) – name of the uploaded image for the small profile artwork

  • small_text (str) – tootltip for the small image

  • small_url (str) – URL to make the small image clickable (opens when small image is clicked)

  • party_id (str) – id of the player’s party, lobby, or group

  • party_size (list) – current size of the player’s party, lobby, or group, and the max in this format: [1,4]

  • join (str) – unique hashed string for chat invitations and ask to join

  • spectate (str) – unique hashed string for spectate button

  • match (str) – unique hashed string for spectate and join

  • buttons (list) – list of dicts for buttons on your profile in the format [{"label": "My Website", "url": "https://qtqt.cf"}, ...], can list up to two buttons

  • instance (bool) – marks the match as a game session with a specific beginning and end

Return type:

pypresence.Response


ActivityType Enum

The ActivityType enum specifies what type of activity is being displayed. It is imported from pypresence.types.

Available values:

  • ActivityType.PLAYING (0) - Shows “Playing {game name}” (default)

  • ActivityType.LISTENING (2) - Shows “Listening to {name}”

  • ActivityType.WATCHING (3) - Shows “Watching {name}”

  • ActivityType.COMPETING (5) - Shows “Competing in {name}”

Example usage:

from pypresence import Presence
from pypresence.types import ActivityType

RPC = Presence(client_id)
RPC.connect()
RPC.update(
    activity_type=ActivityType.LISTENING,
    details="My Favorite Song",
    state="By My Favorite Artist"
)

Note: Discord only supports activity types 0, 2, 3, and 5. Types 1 (STREAMING) and 4 (CUSTOM) are not available via Rich Presence.


StatusDisplayType Enum

The StatusDisplayType enum controls which field from your presence is displayed in the user’s status. It is imported from pypresence.types.

Available values:

  • StatusDisplayType.NAME (0) - Displays the application name (default)

  • StatusDisplayType.STATE (1) - Displays the state field

  • StatusDisplayType.DETAILS (2) - Displays the details field

Example usage:

from pypresence import Presence
from pypresence.types import StatusDisplayType

RPC = Presence(client_id)
RPC.connect()
RPC.update(
    status_display_type=StatusDisplayType.STATE,
    state="Custom Status Message",
    details="What I'm doing"
)

This allows you to control what appears in the user’s Discord status bar while maintaining all information in the full Rich Presence display.


Clickable URLs

The URL parameters (state_url, details_url, large_url, small_url) allow you to make text and images in your Rich Presence clickable. When a user clicks on the associated element, Discord will open the specified URL.

Available URL Parameters:

  • state_url - Makes the state text clickable

  • details_url - Makes the details text clickable

  • large_url - Makes the large image clickable

  • small_url - Makes the small image clickable

Example: Clickable State and Details:

from pypresence import Presence

RPC = Presence(client_id)
RPC.connect()
RPC.update(
    state="Playing an Awesome Game",
    state_url="https://example.com/game",
    details="In the Main Menu",
    details_url="https://example.com/game/menu"
)

Example: Clickable Images:

RPC.update(
    large_image="game_logo",
    large_text="My Game",
    large_url="https://example.com/game",
    small_image="status_icon",
    small_text="Online",
    small_url="https://example.com/status"
)

Example: Combining URLs with Buttons:

RPC.update(
    state="Building Something Cool",
    state_url="https://github.com/username",
    details="pypresence with URL support",
    details_url="https://github.com/qwertyquerty/pypresence",
    large_image="project_logo",
    large_url="https://project-website.com",
    buttons=[
        {"label": "View Project", "url": "https://github.com/username/project"},
        {"label": "Documentation", "url": "https://docs.project.com"}
    ]
)

Notes:

  • URLs work independently - you can set a URL even without the corresponding text/image field

  • URLs must be valid HTTP/HTTPS URLs

  • Clicking on the element will open the URL in the user’s default browser

  • This feature enhances interactivity beyond the traditional button limit (max 2 buttons)