Skip to content

hikari.presences#

Application and entities that are used to describe guilds on Discord.

Activity #

Represents a regular activity that can be associated with a presence.

name class-attribute instance-attribute #

name: str = attrs.field()

The activity name.

state class-attribute instance-attribute #

state: str | None = attrs.field(default=None)

The activities state, if set.

This field can be use to set a custom status or provide more information on the activity.

type class-attribute instance-attribute #

type: ActivityType | int = attrs.field(
    converter=ActivityType, default=ActivityType.PLAYING
)

The activity type.

url class-attribute instance-attribute #

url: str | None = attrs.field(default=None, repr=False)

The activity URL, if set.

Only valid for hikari.presences.ActivityType.STREAMING activities.

ActivityAssets #

Used to represent possible assets for an activity.

large_image class-attribute instance-attribute #

large_image: str | None = attrs.field(repr=False)

The ID of the asset's large image, if set.

large_text class-attribute instance-attribute #

large_text: str | None = attrs.field(repr=True)

The text that'll appear when hovering over the large image, if set.

small_image class-attribute instance-attribute #

small_image: str | None = attrs.field(repr=False)

The ID of the asset's small image, if set.

small_text class-attribute instance-attribute #

small_text: str | None = attrs.field(repr=True)

The text that'll appear when hovering over the small image, if set.

make_large_image_url #

make_large_image_url(
    *,
    file_format: Literal[
        "PNG", "JPEG", "JPG", "WEBP"
    ] = "PNG",
    size: int = 4096,
    lossless: bool = True,
) -> URL | None

Generate the large image asset URL for this application, if set.

If no large image is set or if the asset's dynamic URL (indicated by a {name}: prefix) is not known, this returns None.

Note

file_format, size, and lossless are ignored for images hosted outside of Discord or Discord's media proxy.

PARAMETER DESCRIPTION
file_format

The format to use for this URL.

Supports PNG, JPEG, JPG, and WEBP.

If not specified, the format will be PNG.

TYPE: Literal['PNG', 'JPEG', 'JPG', 'WEBP'] DEFAULT: 'PNG'

size

The size to set for the URL; Can be any power of two between 16 and 4096;

TYPE: int DEFAULT: 4096

lossless

Whether to return a lossless or compressed WEBP image; This is ignored if file_format is not WEBP.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
Optional[URL]

The URL, or None if no large image exists.
RAISES DESCRIPTION
TypeError

If an invalid format is passed for file_format.
ValueError

If size is specified but is not a power of two or not between 16 and 4096.
RuntimeError

If hikari.presences.ActivityAssets.large_image points towards an unknown asset type.

make_small_image_url #

make_small_image_url(
    *,
    file_format: Literal[
        "PNG", "JPEG", "JPG", "WEBP"
    ] = "PNG",
    size: int = 4096,
    lossless: bool = True,
) -> URL | None

Generate the small image asset URL for this application, if set.

If no small image is set or if the asset's dynamic URL (indicated by a {name}: prefix) is not known, this returns None.

Note

file_format, size, and lossless are ignored for images hosted outside of Discord or Discord's media proxy.

PARAMETER DESCRIPTION
file_format

The format to use for this URL.

Supports PNG, JPEG, JPG, and WEBP.

If not specified, the format will be PNG.

TYPE: Literal['PNG', 'JPEG', 'JPG', 'WEBP'] DEFAULT: 'PNG'

size

The size to set for the URL; Can be any power of two between 16 and 4096;

TYPE: int DEFAULT: 4096

lossless

Whether to return a lossless or compressed WEBP image; This is ignored if file_format is not WEBP.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
Optional[URL]

The URL, or None if no small image exists.
RAISES DESCRIPTION
TypeError

If an invalid format is passed for file_format.
ValueError

If size is specified but is not a power of two or not between 16 and 4096.
RuntimeError

If hikari.presences.ActivityAssets.small_image points towards an unknown asset type.

ActivityFlag #

Bases: Flag

Flags that describe what an activity includes.

This can be more than one using bitwise-combinations.

EMBEDDED class-attribute instance-attribute #

EMBEDDED = 1 << 8

An activity that's embedded into a voice channel.

INSTANCE class-attribute instance-attribute #

INSTANCE = 1 << 0

Instance.

JOIN class-attribute instance-attribute #

JOIN = 1 << 1

Join.

JOIN_REQUEST class-attribute instance-attribute #

JOIN_REQUEST = 1 << 3

Join Request.

PARTY_PRIVACY_FRIENDS class-attribute instance-attribute #

PARTY_PRIVACY_FRIENDS = 1 << 6

Party privacy: friends only.

PARTY_PRIVACY_VOICE_CHANNEL class-attribute instance-attribute #

PARTY_PRIVACY_VOICE_CHANNEL = 1 << 7

Party privacy: voice channel only.

PLAY class-attribute instance-attribute #

PLAY = 1 << 5

Play.

SPECTATE class-attribute instance-attribute #

SPECTATE = 1 << 2

Spectate.

SYNC class-attribute instance-attribute #

SYNC = 1 << 4

Sync.

ActivityParty #

Used to represent activity groups of users.

current_size class-attribute instance-attribute #

current_size: int | None = attrs.field(
    eq=False, hash=False, repr=False
)

Current size of this party, if applicable.

id class-attribute instance-attribute #

id: str | None = attrs.field(hash=True, repr=True)

The string id of this party instance, if set.

max_size class-attribute instance-attribute #

max_size: int | None = attrs.field(
    eq=False, hash=False, repr=False
)

Maximum size of this party, if applicable.

ActivitySecret #

The secrets used for interacting with an activity party.

join class-attribute instance-attribute #

join: str | None = attrs.field(repr=False)

The secret used for joining a party, if applicable.

match class-attribute instance-attribute #

match: str | None = attrs.field(repr=False)

The secret used for matching a party, if applicable.

spectate class-attribute instance-attribute #

spectate: str | None = attrs.field(repr=False)

The secret used for spectating a party, if applicable.

ActivityTimestamps #

The datetimes for the start and/or end of an activity session.

end class-attribute instance-attribute #

end: datetime | None = attrs.field(repr=True)

When this activity's session will end, if applicable.

start class-attribute instance-attribute #

start: datetime | None = attrs.field(repr=True)

When this activity's session was started, if applicable.

ActivityType #

Bases: int, Enum

The activity type.

COMPETING class-attribute instance-attribute #

COMPETING = 5

Shows up as Competing in <name>.

CUSTOM class-attribute instance-attribute #

CUSTOM = 4

Shows up as <emoji> <name>.

Warning

As of the time of writing, emoji cannot be used by bot accounts.

LISTENING class-attribute instance-attribute #

LISTENING = 2

Shows up as Listening to <name>.

PLAYING class-attribute instance-attribute #

PLAYING = 0

Shows up as Playing <name>.

STREAMING class-attribute instance-attribute #

STREAMING = 1

Shows up as Streaming and links to a Twitch or YouTube stream/video.

Warning

You MUST provide a valid Twitch or YouTube stream URL to the activity you create in order for this to be valid. If you fail to do this, then the activity WILL NOT update.

WATCHING class-attribute instance-attribute #

WATCHING = 3

Shows up as Watching <name>.

ClientStatus #

The client statuses for this member.

desktop class-attribute instance-attribute #

desktop: Status | str = attrs.field(repr=True)

The status of the target user's desktop session.

mobile class-attribute instance-attribute #

mobile: Status | str = attrs.field(repr=True)

The status of the target user's mobile session.

web class-attribute instance-attribute #

web: Status | str = attrs.field(repr=True)

The status of the target user's web session.

MemberPresence #

Used to represent a guild member's presence.

activities class-attribute instance-attribute #

activities: Sequence[RichActivity] = attrs.field(
    eq=False, hash=False, repr=False
)

All active user activities.

You can assume the first activity is the one that the GUI Discord client will show.

app class-attribute instance-attribute #

app: RESTAware = attrs.field(
    repr=False,
    eq=False,
    hash=False,
    metadata={attrs_extensions.SKIP_DEEP_COPY: True},
)

Client application that models may use for procedures.

client_status class-attribute instance-attribute #

client_status: ClientStatus = attrs.field(
    eq=False, hash=False, repr=False
)

Platform-specific user-statuses.

guild_id class-attribute instance-attribute #

guild_id: Snowflake = attrs.field(hash=True, repr=True)

The ID of the guild this presence belongs to.

user_id class-attribute instance-attribute #

user_id: Snowflake = attrs.field(repr=True, hash=True)

The ID of the user this presence belongs to.

visible_status class-attribute instance-attribute #

visible_status: Status | str = attrs.field(
    eq=False, hash=False, repr=True
)

This user's current status being displayed by the client.

fetch_member async #

fetch_member() -> Member

Fetch the member this presence is for.

RETURNS DESCRIPTION
Member

The requested member.
RAISES DESCRIPTION
UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).
NotFoundError

If the user is not found.
RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
InternalServerError

If an internal error occurs on Discord while handling the request.

fetch_user async #

fetch_user() -> User

Fetch the user this presence is for.

RETURNS DESCRIPTION
User

The requested user.
RAISES DESCRIPTION
UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).
NotFoundError

If the user is not found.
RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
InternalServerError

If an internal error occurs on Discord while handling the request.

RichActivity #

Bases: Activity

Represents a rich activity that can be associated with a presence.

application_id class-attribute instance-attribute #

application_id: Snowflake | None = attrs.field(repr=False)

The ID of the application this activity is for, if applicable.

assets class-attribute instance-attribute #

assets: ActivityAssets | None = attrs.field(repr=False)

Images and their hover over text for the activity.

buttons class-attribute instance-attribute #

buttons: Sequence[str] = attrs.field(repr=False)

A sequence of up to 2 of the button labels shown in this rich presence.

created_at class-attribute instance-attribute #

created_at: datetime = attrs.field(repr=False)

When this activity was added to the user's session.

details class-attribute instance-attribute #

details: str | None = attrs.field(repr=False)

The text that describes what the activity's target is doing, if set.

emoji class-attribute instance-attribute #

emoji: Emoji | None = attrs.field(repr=False)

The emoji of this activity, if it is a custom status and set.

flags class-attribute instance-attribute #

flags: ActivityFlag | None = attrs.field(repr=False)

Flags that describe what the activity includes, if present.

is_instance class-attribute instance-attribute #

is_instance: bool | None = attrs.field(repr=False)

Whether this activity is an instanced game session.

party class-attribute instance-attribute #

party: ActivityParty | None = attrs.field(repr=False)

Information about the party associated with this activity, if set.

secrets class-attribute instance-attribute #

secrets: ActivitySecret | None = attrs.field(repr=False)

Secrets for Rich Presence joining and spectating.

timestamps class-attribute instance-attribute #

timestamps: ActivityTimestamps | None = attrs.field(
    repr=False
)

The timestamps for when this activity's current state will start and end, if applicable.

Status #

Bases: str, Enum

The status of a member.

DO_NOT_DISTURB class-attribute instance-attribute #

DO_NOT_DISTURB = 'dnd'

Do not disturb/red.

IDLE class-attribute instance-attribute #

IDLE = 'idle'

Idle/yellow.

OFFLINE class-attribute instance-attribute #

OFFLINE = 'offline'

Offline or invisible/grey.

ONLINE class-attribute instance-attribute #

ONLINE = 'online'

Online/green.