Guild Scheduled Event

Reference for Discord scheduled event objects and management endpoints.

A representation of a scheduled event in a guild.

Guild Scheduled Event Object

Guild Scheduled Event Structure

Field	Type	Description
id	snowflake	the id of the scheduled event
guild_id	snowflake	the guild id which the scheduled event belongs to
channel_id **	?snowflake	the channel id in which the scheduled event will be hosted, or null if scheduled entity type is EXTERNAL
creator_id? *	?snowflake	the id of the user that created the scheduled event *
name	string	the name of the scheduled event (1-100 characters)
description?	?string	the description of the scheduled event (1-1000 characters)
scheduled_start_time	ISO8601 timestamp	the time the scheduled event will start
scheduled_end_time **	?ISO8601 timestamp	the time the scheduled event will end, required if entity_type is EXTERNAL
privacy_level	privacy level	the privacy level of the scheduled event
status	event status	the status of the scheduled event
entity_type	scheduled entity type	the type of the scheduled event
entity_id	?snowflake	the id of an entity associated with a guild scheduled event
entity_metadata **	?entity metadata	additional metadata for the guild scheduled event
creator?	user object	the user that created the scheduled event
user_count?	integer	the number of users subscribed to the scheduled event
image?	?string	the cover image hash of the scheduled event
recurrence_rule	?recurrence rule	the definition for how often this event should recur

* creator_id will be null and creator will not be included for events created before October 25th, 2021, when the concept of creator_id was introduced and tracked.

** See field requirements by entity type to understand the relationship between entity_type and the following fields: channel_id, entity_metadata, and scheduled_end_time

Guild Scheduled Event Privacy Level

Level	Value	Description
GUILD_ONLY	2	the scheduled event is only accessible to guild members

Guild Scheduled Event Entity Types

Type	Value
STAGE_INSTANCE	1
VOICE	2
EXTERNAL	3

Field Requirements By Entity Type

The following table shows field requirements based on current entity type.

value : This field is required to be a non-null value

null : This field is required to be null

- : No strict requirements

Entity Type	channel_id	entity_metadata	scheduled_end_time
STAGE_INSTANCE	value	null	-
VOICE	value	null	-
EXTERNAL	null	value *	value

* entity_metadata with a non-null location must be provided

Guild Scheduled Event Status

Type	Value
SCHEDULED	1
ACTIVE	2
COMPLETED *	3
CANCELED *	4

* Once status is set to COMPLETED or CANCELED, the status can no longer be updated

Valid Guild Scheduled Event Status Transitions

SCHEDULED —> ACTIVE

ACTIVE --------> COMPLETED

SCHEDULED —> CANCELED

Guild Scheduled Event Entity Metadata

Field	Type	Description
location? *	string	location of the event (1-100 characters)

* required for events with 'entity_type': EXTERNAL

Guild Scheduled Event User Object

Guild Scheduled Event User Structure

Field	Type	Description
guild_scheduled_event_id	snowflake	the scheduled event id which the user subscribed to
user	user	user which subscribed to an event
member?	guild member	guild member data for this user for the guild which this event belongs to, if any

Guild Scheduled Event Recurrence Rule Object

Discord’s recurrence rule is a subset of the behaviors defined in the iCalendar RFC and implemented by python’s dateutil rrule

There are currently many limitations to this system. Please see “System limitations” below

Guild Scheduled Event Recurrence Rule Structure

Field	Type	Description
start	ISO8601 timestamp	Starting time of the recurrence interval
end [1]	?ISO8601 timestamp	Ending time of the recurrence interval
frequency	recurrence rule - frequency object	How often the event occurs
interval	int	The spacing between the events, defined by frequency. For example, frequency of WEEKLY and an interval of 2 would be “every-other week”
by_weekday	?array of recurrence rule - weekday	Set of specific days within a week for the event to recur on
by_n_weekday	?array of recurrence rule - n_weekday objects	List of specific days within a specific week (1-5) to recur on
by_month	?array of recurrence rule - month	Set of specific months to recur on
by_month_day	?array of int	Set of specific dates within a month to recur on
by_year_day [1]	?array of int	Set of days within a year to recur on (1-364)
count [1]	?int	The total amount of times that the event is allowed to recur before stopping

[1] - Cannot be set externally currently.

System limitations

Recurrence rules are powerful, but they have some specific restrictions

The current system limitations are present due to how reoccurring event data needs to be displayed in the client. In the future, we would like to open the system up to have fewer / none of these restrictions.

The following fields cannot be set by the client / application

• count
• end
• by_year_day

The following combinations are mutually exclusive

• by_weekday
• by_n_weekday
• by_month + by_month_day

by_weekday

• Only valid for daily and weekly events (frequency of DAILY (0) or WEEKLY (1))
• when used in a daily event (frequency is DAILY (0))
  • The values present in the by_weekday event must be a “known set” of weekdays.
  • The following are current allowed “sets”
    • Monday - Friday ([0, 1, 2, 3, 4])
    • Tuesday - Saturday ([1, 2, 3, 4, 5])
    • Sunday - Thursday ([6, 0, 1, 2, 3])
    • Friday & Saturday ([4, 5])
    • Saturday & Sunday ([5, 6])
    • Sunday & Monday ([6, 0])
• when used in a weekly event (frequency is WEEKLY (1))
  • by_weekday array currently can only be a length of 1
    • i.e: You can only select a single day within a week to have a recurring event on
    • If you wish to have multiple days within a week have a recurring event, please use a frequency of DAILY
  • Also, see interval below for “every-other” week information

by_n_weekday

• Only valid for monthly events (frequency of MONTHLY (1))
• by_n_weekday array currently can only be a length of 1
  • i.e: You can only select a single day within a month to have a recurring event on

by_month and by_month_day

• Only valid for annual event (frequency is YEARLY (0))
• both by_month and by_month_day must be provided
• both by_month and by_month_day arrays must have a length of 1
  • (i.e: You can only set a single date for annual events)

interval can only be set to a value other than 1 when frequency is set to WEEKLY (1)

• In this situation, interval can be set to 2
• This allowance enables “every-other week” events
• Due to the limitations placed on by_weekday this means that if you wish to use “every-other week” functionality you can only do so for a single day.

Examples

Simple examples of some common Recurrent Rules

Every weekday

frequency = 3 // Frequency.DAILY
interval = 1
by_weekday = [0, 1, 2, 3, 4] // [Weekday.MONDAY, ..., Weekday.FRIDAY]

Every Wednesday

frequency = 2 // Frequency.WEEKLY
interval = 1
by_weekday = [2] // [Weekday.WEDNESDAY]

Every other Wednesday

frequency = 2 // Frequency.WEEKLY
interval = 2
by_weekday = [2] // [Weekday.WEDNESDAY]

Monthly on the fourth Wednesday

frequency = 1 // Frequency.MONTHLY
interval = 1
by_n_weekday = [{
  n: 4,
  day: 2 // Weekday.WEDNESDAY
}]

Annually on July 24

frequency = 0 // Frequency.YEARLY
interval = 1
by_month = [7] // [Month.JULY]
by_month_day = [24]

Guild Scheduled Event Recurrence Rule - Frequency

Type	Value
YEARLY	0
MONTHLY	1
WEEKLY	2
DAILY	3

Guild Scheduled Event Recurrence Rule - Weekday

Type	Value
MONDAY	0
TUESDAY	1
WEDNESDAY	2
THURSDAY	3
FRIDAY	4
SATURDAY	5
SUNDAY	6

Guild Scheduled Event Recurrence Rule - N_Weekday Structure

Field	Type	Description
n	int	The week to reoccur on. 1 - 5
day	recurrence rule - weekday	The day within the week to reoccur on

Guild Scheduled Event Recurrence Rule - Month

Type	Value
JANUARY	1
FEBRUARY	2
MARCH	3
APRIL	4
MAY	5
JUNE	6
JULY	7
AUGUST	8
SEPTEMBER	9
OCTOBER	10
NOVEMBER	11
DECEMBER	12

List Scheduled Events for Guild

Returns a list of guild scheduled event objects for the given guild.

Query String Params

Field	Type	Description
with_user_count?	boolean	include number of users subscribed to each event

Create Guild Scheduled Event

Create a guild scheduled event in the guild. Returns a guild scheduled event object on success. Fires a Guild Scheduled Event Create Gateway event.

A guild can have a maximum of 100 events with SCHEDULED or ACTIVE status at any time.

This endpoint supports the X-Audit-Log-Reason header.

JSON Params

Field	Type	Description
channel_id? *	snowflake *	the channel id of the scheduled event.
entity_metadata? **	entity metadata	the entity metadata of the scheduled event
name	string	the name of the scheduled event
privacy_level	privacy level	the privacy level of the scheduled event
scheduled_start_time	ISO8601 timestamp	the time to schedule the scheduled event
scheduled_end_time? **	ISO8601 timestamp	the time when the scheduled event is scheduled to end
description?	string	the description of the scheduled event
entity_type	entity type	the entity type of the scheduled event
image?	image data	the cover image of the scheduled event
recurrence_rule?	recurrence rule	the definition for how often this event should recur

* Optional for events with 'entity_type': EXTERNAL

** Required for events with 'entity_type': EXTERNAL

Get Guild Scheduled Event

Get a guild scheduled event. Returns a guild scheduled event object on success.

Query String Params

Field	Type	Description
with_user_count?	boolean	include number of users subscribed to this event

Modify Guild Scheduled Event

Modify a guild scheduled event. Returns the modified guild scheduled event object on success. Fires a Guild Scheduled Event Update Gateway event.

To start or end an event, use this endpoint to modify the event’s status field.

This endpoint supports the X-Audit-Log-Reason header.

This endpoint silently discards entity_metadata for non-EXTERNAL events.

All parameters to this endpoint are optional.

JSON Params

Field	Type	Description
channel_id? *	?snowflake	the channel id of the scheduled event, set to null if changing entity type to EXTERNAL
entity_metadata?	?entity metadata	the entity metadata of the scheduled event
name?	string	the name of the scheduled event
privacy_level?	privacy level	the privacy level of the scheduled event
scheduled_start_time?	ISO8601 timestamp	the time to schedule the scheduled event
scheduled_end_time? *	ISO8601 timestamp	the time when the scheduled event is scheduled to end
description?	?string	the description of the scheduled event
entity_type? *	event entity type	the entity type of the scheduled event
status?	event status	the status of the scheduled event
image?	image data	the cover image of the scheduled event
recurrence_rule?	?recurrence rule	the definition for how often this event should recur

* If updating entity_type to EXTERNAL:

• channel_id is required and must be set to null
• entity_metadata with a location field must be provided
• scheduled_end_time must be provided

Delete Guild Scheduled Event

Delete a guild scheduled event. Returns a 204 on success. Fires a Guild Scheduled Event Delete Gateway event.

Get Guild Scheduled Event Users

Get a list of guild scheduled event users subscribed to a guild scheduled event. Returns a list of guild scheduled event user objects on success. Guild member data, if it exists, is included if the with_member query parameter is set.

Query String Params

Field	Type	Description	Default
limit?	number	number of users to return (up to maximum 100)	100
with_member?	boolean	include guild member data if it exists	false
before? *	snowflake	consider only users before given user id	null
after? *	snowflake	consider only users after given user id	null

* Provide a user id to before and after for pagination. Users will always be returned in ascending order by user_id. If both before and after are provided, only before is respected. Fetching users in-between before and after is not supported.

Guild Scheduled Event Status Update Automation

NOTE: status and entity_type here are expressed by name rather than their value for readability

An active scheduled event for a stage channel where all users have left the stage channel will automatically end a few minutes after the last user leaves the channel

When an event with 'status': ACTIVE and 'entity_type': STAGE_INSTANCE has no users connected to the stage channel for a certain period of time (on the order of minutes), the event status will be automatically set to COMPLETED.

An active scheduled event for a voice channel where all users have left the voice channel will automatically end a few minutes after the last user leaves the channel

When an event with 'status': ACTIVE and 'entity_type': VOICE has no users connected to the voice channel for a certain period of time (on the order of minutes), the event status will be automatically set to COMPLETED.

An external event will automatically begin at its scheduled start time

An event with 'entity_type': EXTERNAL at its scheduled_start_time will automatically have status set to ACTIVE.

An external event will automatically end at its scheduled end time

An event with 'entity_type': EXTERNAL at its scheduled_end_time will automatically have status set to COMPLETED.

Any scheduled event which has not begun after its scheduled start time will be automatically cancelled after a few hours

Any event with 'status': SCHEDULED after a certain time interval (on the order of hours) beyond its scheduled_start_time will have its status automatically set to CANCELLED.

Guild Scheduled Event Permissions Requirements

NOTE: entity_type is expressed by name rather than value for readability

A user must be a member of the guild in order to access events for that guild unless the guild is public. If a guild is public, events in that guild may be visible depending on the event type and the permissions of any channels associated with the event.

Permissions for events with entity_type: STAGE_INSTANCE

The computed permissions for the user in the channel_id associated with the event must include:

Get Permissions

• VIEW_CHANNEL

Create Permissions

• CREATE_EVENTS
• MANAGE_CHANNELS
• MUTE_MEMBERS
• MOVE_MEMBERS

Modify/Delete Permissions

• If the event was created by the current user, either CREATE_EVENTS or MANAGE_EVENTS. Otherwise, MANAGE_EVENTS
• MANAGE_CHANNELS
• MUTE_MEMBERS
• MOVE_MEMBERS

Permissions for events with entity_type: VOICE

The computed permissions for the user in the channel_id associated with the event must include:

Get Permissions

• VIEW_CHANNEL

Create permissions

• CREATE_EVENTS
• VIEW_CHANNEL
• CONNECT

Modify/Delete Permissions

• If the event was created by the current user, either CREATE_EVENTS or MANAGE_EVENTS. Otherwise, MANAGE_EVENTS
• VIEW_CHANNEL
• CONNECT

Permissions for events with entity_type: EXTERNAL

The user’s guild-level permissions must include:

Get Permissions

• No permissions required

Create permissions

• CREATE_EVENTS

Modify/Delete Permissions

• If the event was created by the current user, either CREATE_EVENTS or MANAGE_EVENTS. Otherwise, MANAGE_EVENTS