Guild Scheduled Events

This section documents everything related to Guild Scheduled Events.

Discord Models

GuildScheduledEventRecurrenceRule

Attributes
class disnake.GuildScheduledEventRecurrenceRule[source]

Represents the recurrence rule payload used when creating a scheduled event.

This structure defines how and when a scheduled event repeats.

Certain combinations and values are restricted by the Discord client. See the official Discord documentation on recurrence rules for detailed constraints and valid combinations.

New in version 2.11.

start

An ISO8601 timestamp representing the start time of the recurrence interval.

Type:

str

frequency

How often the event repeats.

Type:

GuildScheduledEventFrequency

interval

The spacing between each occurrence. For example, a value of 2 with a weekly frequency would mean “every other week”.

Valid only when frequency is GuildScheduledEventFrequency.WEEKLY if greater than 1.

Type:

int

by_weekday

A list of GuildScheduledEventWeekday values indicating the weekdays the event repeats on.

Valid only when frequency is GuildScheduledEventFrequency.DAILY or GuildScheduledEventFrequency.WEEKLY.

  • For DAILY frequency: Must match one of the allowed weekday sets.

  • For WEEKLY frequency: May only contain one entry.

Type:

Optional[List[GuildScheduledEventWeekday]]

by_n_weekday

A list of weekday-within-week combinations, such as “2nd Tuesday”.

Each item represents a specific week (1-5) and a weekday (0 = Monday, …, 6 = Sunday), indicating a recurring event like “third Friday of every month”.

Type:

Optional[List[GuildScheduledEventNWeekday]]

by_month

A list of month values, represented by GuildScheduledEventMonth.

Type:

Optional[List[GuildScheduledEventMonth]]

by_month_day

A list of days in the month (1-31).

Type:

Optional[List[int]]

GuildScheduledEvent

Attributes
Methods
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:

Optional[int]

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:

Optional[int]

creator

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

Type:

Optional[User]

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:

Optional[datetime.datetime]

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:

Optional[int]

entity_metadata

Additional metadata for the guild scheduled event.

Type:

GuildScheduledEventMetadata

recurrence_rule

An optional recurrence rule that specifies how the event should repeat over time. This allows for recurring scheduled events such as weekly meetings or monthly check-ins.

Type:

GuildScheduledEventRecurrenceRule

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:

Optional[int]

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:

Optional[Guild]

channel

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

This will be None if entity_type is GuildScheduledEventEntityType.external.

Type:

Optional[abc.GuildChannel]

property image[source]

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

Type:

Optional[Asset]

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 (Optional[str]) – The description of the guild scheduled event.

  • image (Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]) –

    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 (Optional[abc.Snowflake]) –

    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 (Optional[datetime.datetime]) – 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 (Optional[GuildScheduledEventMetadata]) – The entity metadata of the guild scheduled event.

  • status (GuildScheduledEventStatus) –

    The status of the guild scheduled event.

    See also start(), end(), and cancel().

  • reason (Optional[str]) – The reason for editing the guild scheduled event. Shows up on the audit log.

Raises:
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 (Optional[str]) – 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 (Optional[str]) – 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 (Optional[str]) – 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 (Optional[int]) – The number of users to retrieve.

  • with_members (bool) – Whether to include some users as members. Defaults to True.

  • before (Optional[abc.Snowflake]) – Retrieve users before this object.

  • after (Optional[abc.Snowflake]) – 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:

Union[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
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
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:

Optional[str]

GuildScheduledEventNWeekday

Attributes
class disnake.GuildScheduledEventNWeekday(*, n, day)[source]

Represents a specific weekday occurrence within a month for recurrence rules.

New in version 2.11.

n

The week number (1-5) that the event should occur on.

Type:

int

day

The day of the week (e.g. GuildScheduledEventWeekday.TUESDAY) the event should occur on.

Type:

GuildScheduledEventWeekday

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.

GuildScheduledEventFrequency

class disnake.GuildScheduledEventFrequency[source]

Represents the frequency of recurrence for a scheduled event.

This determines how often the event should repeat, such as daily, weekly, monthly, or yearly.

New in version 2.11.

YEARLY

The event occurs once a year.

MONTHLY

The event occurs once a month.

WEEKLY

The event occurs once a week.

DAILY

The event occurs every day.

GuildScheduledEventWeekday

class disnake.GuildScheduledEventWeekday[source]

Represents the day of the week used in recurrence rules.

Used for specifying which days an event should recur on.

New in version 2.11.

MONDAY

Monday.

TUESDAY

Tuesday.

WEDNESDAY

Wednesday.

THURSDAY

Thursday.

FRIDAY

Friday.

SATURDAY

Saturday.

SUNDAY

Sunday.

GuildScheduledEventMonth

class disnake.GuildScheduledEventMonth[source]

Represents the month of the year used in recurrence rules.

Used for specifying which months an event should recur on.

New in version 2.11.

JANUARY

January.

FEBRUARY

February.

MARCH

March.

APRIL

April.

MAY

May.

JUNE

June.

JULY

July.

AUGUST

August.

SEPTEMBER

September.

OCTOBER

October.

NOVEMBER

November.

DECEMBER

December.

Events