Skip to main content
A representation of a scheduled event in a guild.

​
Guild Scheduled Event Object

Guild Scheduled Event Structure
FieldTypeDescription
idsnowflakethe id of the scheduled event
guild_idsnowflakethe guild id which the scheduled event belongs to
channel_id **?snowflakethe channel id in which the scheduled event will be hosted, or null if scheduled entity type is EXTERNAL
creator_id? *?snowflakethe id of the user that created the scheduled event *
namestringthe name of the scheduled event (1-100 characters)
description??stringthe description of the scheduled event (1-1000 characters)
scheduled_start_timeISO8601 timestampthe time the scheduled event will start
scheduled_end_time **?ISO8601 timestampthe time the scheduled event will end, required if entity_type is EXTERNAL
privacy_levelprivacy levelthe privacy level of the scheduled event
statusevent statusthe status of the scheduled event
entity_typescheduled entity typethe type of the scheduled event
entity_id?snowflakethe id of an entity associated with a guild scheduled event
entity_metadata **?entity metadataadditional metadata for the guild scheduled event
creator?user objectthe user that created the scheduled event
user_count?integerthe number of users subscribed to the scheduled event
image??stringthe cover image hash of the scheduled event
recurrence_rule?recurrence rulethe 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
LevelValueDescription
GUILD_ONLY2the scheduled event is only accessible to guild members
Guild Scheduled Event Entity Types
TypeValue
STAGE_INSTANCE1
VOICE2
EXTERNAL3
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 Typechannel_identity_metadatascheduled_end_time
STAGE_INSTANCEvaluenull-
VOICEvaluenull-
EXTERNALnullvalue *value
* entity_metadata with a non-null location must be provided
Guild Scheduled Event Status
TypeValue
SCHEDULED1
ACTIVE2
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
FieldTypeDescription
location? *stringlocation of the event (1-100 characters)
* required for events with 'entity_type': EXTERNAL

​
Guild Scheduled Event User Object

Guild Scheduled Event User Structure
FieldTypeDescription
guild_scheduled_event_idsnowflakethe scheduled event id which the user subscribed to
useruseruser which subscribed to an event
member?guild memberguild 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
FieldTypeDescription
startISO8601 timestampStarting time of the recurrence interval
end [1]?ISO8601 timestampEnding time of the recurrence interval
frequencyrecurrence rule - frequency objectHow often the event occurs
intervalintThe 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 - weekdaySet of specific days within a week for the event to recur on
by_n_weekday?array of recurrence rule - n_weekday objectsList of specific days within a specific week (1-5) to recur on
by_month?array of recurrence rule - monthSet of specific months to recur on
by_month_day?array of intSet of specific dates within a month to recur on
by_year_day [1]?array of intSet of days within a year to recur on (1-364)
count [1]?intThe total amount of times that the event is allowed to recur before stopping
[1] - Cannot be set externally currently.
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.
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
TypeValue
YEARLY0
MONTHLY1
WEEKLY2
DAILY3
Guild Scheduled Event Recurrence Rule - Weekday
TypeValue
MONDAY0
TUESDAY1
WEDNESDAY2
THURSDAY3
FRIDAY4
SATURDAY5
SUNDAY6
Guild Scheduled Event Recurrence Rule - N_Weekday Structure
FieldTypeDescription
nintThe week to reoccur on. 1 - 5
dayrecurrence rule - weekdayThe day within the week to reoccur onguild member data for this user for the guild which this event belongs to, if any
Guild Scheduled Event Recurrence Rule - Month
TypeValue
JANUARY1
FEBRUARY2
MARCH3
APRIL4
MAY5
JUNE6
JULY7
AUGUST8
SEPTEMBER9
OCTOBER10
NOVEMBER11
DECEMBER12

​
List Scheduled Events for Guild

GET/guilds/{guild.id}/scheduled-events
Returns a list of guild scheduled event objects for the given guild.
Query String Params
FieldTypeDescription
with_user_count?booleaninclude number of users subscribed to each event

​
Create Guild Scheduled Event

POST/guilds/{guild.id}/scheduled-events
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
FieldTypeDescription
channel_id? *snowflake *the channel id of the scheduled event.
entity_metadata? **entity metadatathe entity metadata of the scheduled event
namestringthe name of the scheduled event
privacy_levelprivacy levelthe privacy level of the scheduled event
scheduled_start_timeISO8601 timestampthe time to schedule the scheduled event
scheduled_end_time? **ISO8601 timestampthe time when the scheduled event is scheduled to end
description?stringthe description of the scheduled event
entity_typeentity typethe entity type of the scheduled event
image?image datathe cover image of the scheduled event
recurrence_rule?recurrence rulethe 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/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}
Get a guild scheduled event. Returns a guild scheduled event object on success.
Query String Params
FieldTypeDescription
with_user_count?booleaninclude number of users subscribed to this event

​
Modify Guild Scheduled Event

PATCH/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}
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
FieldTypeDescription
channel_id? *?snowflakethe channel id of the scheduled event, set to null if changing entity type to EXTERNAL
entity_metadata??entity metadatathe entity metadata of the scheduled event
name?stringthe name of the scheduled event
privacy_level?privacy levelthe privacy level of the scheduled event
scheduled_start_time?ISO8601 timestampthe time to schedule the scheduled event
scheduled_end_time? *ISO8601 timestampthe time when the scheduled event is scheduled to end
description??stringthe description of the scheduled event
entity_type? *event entity typethe entity type of the scheduled event
status?event statusthe status of the scheduled event
image?image datathe cover image of the scheduled event
recurrence_rule??recurrence rulethe 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/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}
Delete a guild scheduled event. Returns a 204 on success. Fires a Guild Scheduled Event Delete Gateway event.

​
Get Guild Scheduled Event Users

GET/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/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
FieldTypeDescriptionDefault
limit?numbernumber of users to return (up to maximum 100)100
with_member?booleaninclude guild member data if it existsfalse
before? *snowflakeconsider only users before given user idnull
after? *snowflakeconsider only users after given user idnull
* 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 lurkable. If a guild is lurkable, events in that guild may be visible to lurkers 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