Guild Scheduled Events¶

This section documents everything related to Guild Scheduled Events.

Discord Models¶

GuildScheduledEvent¶

Methods

asynccancel
asyncdelete
asyncedit
asyncend
asyncfetch_users
asyncstart

class disnake.GuildScheduledEvent[source]¶

Represents a guild scheduled event.

New in version 2.3.

x == y: Checks if two guild scheduled events are equal.

x != y: Checks if two guild scheduled events are not equal.

hash(x): Returns the guild scheduled event’s hash.

id¶

The ID of the guild scheduled event.

Type:: int

guild_id¶

The guild ID which the guild scheduled event belongs to.

Type:: int

channel_id¶

The channel ID in which the guild scheduled event will be hosted. This field is None if entity_type is GuildScheduledEventEntityType.external.

Type:: int | None

creator_id¶

The ID of the user that created the guild scheduled event. This field is None for events created before October 25th, 2021.

Type:: int | None

creator¶

The user that created the guild scheduled event. This field is None for events created before October 25th, 2021.

Type:: User | None

name¶

The name of the guild scheduled event (1-100 characters).

Type:: str

description¶

The description of the guild scheduled event (1-1000 characters).

Type:: str

scheduled_start_time¶

The time when the guild scheduled event will start.

Type:: datetime.datetime

scheduled_end_time¶

The time when the guild scheduled event will end, or None if the event does not have a scheduled time to end.

Type:: datetime.datetime | None

privacy_level¶

The privacy level of the guild scheduled event.

Type:: GuildScheduledEventPrivacyLevel

status¶

The status of the guild scheduled event.

Type:: GuildScheduledEventStatus

entity_type¶

The type of the guild scheduled event.

Type:: GuildScheduledEventEntityType

entity_id¶

The ID of an entity associated with the guild scheduled event.

Type:: int | None

entity_metadata¶

Additional metadata for the guild scheduled event.

Type:: GuildScheduledEventMetadata

user_count¶

The number of users subscribed to the guild scheduled event. If the guild scheduled event was fetched with with_user_count set to False, this field is None.

Type:: int | None

property created_at[source]¶

Returns the guild scheduled event’s creation time in UTC.

New in version 2.6.

Type:: datetime.datetime

property url[source]¶

The guild scheduled event’s URL.

New in version 2.6.

Type:: str

guild¶

The guild which the guild scheduled event belongs to.

Type:: Guild | None

channel¶

The channel in which the guild scheduled event will be hosted.

This will be None if entity_type is GuildScheduledEventEntityType.external.

Type:: abc.GuildChannel | None

property image[source]¶

The cover image asset of the guild scheduled event, if available.

Type:: Asset | None

await delete()[source]¶

This function is a coroutine.

Deletes the guild scheduled event.

You must have manage_events permission to do this.

Raises:

Forbidden – You do not have proper permissions to delete the event.
NotFound – The event does not exist.
HTTPException – Deleting the event failed.

await edit(*, name=..., description=..., image=..., channel=..., privacy_level=..., scheduled_start_time=..., scheduled_end_time=..., entity_type=..., entity_metadata=..., status=..., reason=None)[source]¶

This function is a coroutine.

Edits the guild scheduled event.

You must have manage_events permission to do this.

Changed in version 2.6: Updates must follow requirements of Guild.create_scheduled_event()

Changed in version 2.6: Now raises TypeError instead of ValueError for invalid parameter types.

Changed in version 2.6: Removed channel_id parameter in favor of channel.

Changed in version 2.6: Naive datetime parameters are now assumed to be in the local timezone instead of UTC.

Parameters:

name (str) – The name of the guild scheduled event.
description (str | None) – The description of the guild scheduled event.
image (bytes | Asset | Emoji | PartialEmoji | StickerItem | Sticker | None) –
The cover image of the guild scheduled event. Set to None to remove the image.

New in version 2.4.

Changed in version 2.5: Now accepts various resource types in addition to bytes.
channel (abc.Snowflake | None) –
The channel in which the guild scheduled event will be hosted. Set to None if changing entity_type to GuildScheduledEventEntityType.external.

New in version 2.6.
privacy_level (GuildScheduledEventPrivacyLevel) – The privacy level of the guild scheduled event.
scheduled_start_time (datetime.datetime) – The time to schedule the guild scheduled event. If the datetime is naive, it is assumed to be local time.
scheduled_end_time (datetime.datetime | None) – The time when the guild scheduled event is scheduled to end. If the datetime is naive, it is assumed to be local time.
entity_type (GuildScheduledEventEntityType) – The entity type of the guild scheduled event.
entity_metadata (GuildScheduledEventMetadata | None) – The entity metadata of the guild scheduled event.
status (GuildScheduledEventStatus) –
The status of the guild scheduled event.

See also start(), end(), and cancel().
reason (str | None) – The reason for editing the guild scheduled event. Shows up on the audit log.

Raises:

Forbidden – You do not have proper permissions to edit the event.
NotFound – The event does not exist or the image asset couldn’t be found.
HTTPException – Editing the event failed.
TypeError – The image asset is a lottie sticker (see Sticker.read()), one of entity_type, privacy_level, entity_metadata or status is not of the correct type, or the provided channel’s type is neither ChannelType.voice nor ChannelType.stage_voice.

Returns:

The newly updated guild scheduled event instance.

Return type:

GuildScheduledEvent

await start(*, reason=None)[source]¶

This function is a coroutine.

Starts the guild scheduled event.

Changes the event status to active.

You must have manage_events permission to do this.

New in version 2.7.

Parameters:

reason (str | None) – The reason for starting the guild scheduled event. Shows up on the audit log.

Raises:

ValueError – The event has already started or ended, or was cancelled.
Forbidden – You do not have permissions to start the event.
HTTPException – Starting the event failed.

Returns:

The started guild scheduled event instance.

Return type:

GuildScheduledEvent

await end(*, reason=None)[source]¶

This function is a coroutine.

Ends the guild scheduled event.

Changes the event status to completed.

You must have manage_events permission to do this.

New in version 2.7.

Parameters:

reason (str | None) – The reason for ending the guild scheduled event. Shows up on the audit log.

Raises:

ValueError – The event has not started yet, has already ended, or was cancelled.
Forbidden – You do not have permissions to end the event.
HTTPException – Ending the event failed.

Returns:

The ended guild scheduled event instance.

Return type:

GuildScheduledEvent

await cancel(*, reason=None)[source]¶

This function is a coroutine.

Cancels the guild scheduled event.

Changes the event status to cancelled.

You must have manage_events permission to do this.

New in version 2.7.

Parameters:

reason (str | None) – The reason for cancelling the guild scheduled event. Shows up on the audit log.

Raises:

ValueError – The event has already started or ended, or was already cancelled.
Forbidden – You do not have permissions to cancel the event.
HTTPException – Cancelling the event failed.

Returns:

The cancelled guild scheduled event instance.

Return type:

GuildScheduledEvent

fetch_users(*, limit=None, with_members=True, before=None, after=None)[source]¶

This function is a coroutine.

Returns an AsyncIterator of users subscribed to the guild scheduled event.

If before is specified, users are returned in reverse order, i.e. starting with the highest ID.

Changed in version 2.5: Now returns an AsyncIterator instead of a list of the first 100 users.

Parameters:

limit (int | None) – The number of users to retrieve.
with_members (bool) – Whether to include some users as members. Defaults to True.
before (abc.Snowflake | None) – Retrieve users before this object.
after (abc.Snowflake | None) – Retrieve users after this object.

Raises:

Forbidden – You do not have proper permissions to fetch the users.
NotFound – The event does not exist.
HTTPException – Retrieving the users failed.

Yields:

User | Member – The member (if retrievable) or user subscribed to the guild scheduled event.

Examples

Usage

async for user in event.fetch_users(limit=500):
    print(user.name)

Flattening into a list

users = await event.fetch_users(limit=250).flatten()

RawGuildScheduledEventUserActionEvent¶

Attributes

event_id
guild_id
user_id

class disnake.RawGuildScheduledEventUserActionEvent[source]¶

Represents the event payload for an on_raw_guild_scheduled_event_subscribe() and on_raw_guild_scheduled_event_unsubscribe() events.

New in version 2.3.

event_id¶

The ID of the guild scheduled event that the user subscribed to or unsubscribed from.

Type:: int

user_id¶

The ID of the user doing the action.

Type:: int

guild_id¶

The guild ID where the guild scheduled event is located.

Type:: int

Data Classes¶

GuildScheduledEventMetadata¶

Attributes

location

class disnake.GuildScheduledEventMetadata(*, location=None)[source]¶

Represents a guild scheduled event entity metadata.

New in version 2.3.

location¶

The location of the guild scheduled event. If GuildScheduledEvent.entity_type is GuildScheduledEventEntityType.external, this value is not None.

Type:: str | None

Enumerations¶

GuildScheduledEventEntityType¶

class disnake.GuildScheduledEventEntityType[source]¶

Represents the type of a guild scheduled event entity.

New in version 2.3.

stage_instance¶: The guild scheduled event will take place in a stage channel.

voice¶: The guild scheduled event will take place in a voice channel.

external¶: The guild scheduled event will take place in a custom location.

GuildScheduledEventStatus¶

class disnake.GuildScheduledEventStatus[source]¶

Represents the status of a guild scheduled event.

New in version 2.3.

scheduled¶: Represents a scheduled event.

active¶: Represents an active event.

completed¶: Represents a completed event.

canceled¶: Represents a canceled event.

cancelled¶: An alias for canceled.

New in version 2.6.

GuildScheduledEventPrivacyLevel¶

class disnake.GuildScheduledEventPrivacyLevel[source]¶

Represents the privacy level of a guild scheduled event.

New in version 2.3.

guild_only¶: The guild scheduled event is only for a specific guild.