Guild Scheduled Events

Scheduled events are a way to plan and organize events in a guild. They can be associated with a stage channel, voice channel, or an external location.

Guild Scheduled Event Object

Guild Scheduled Event Structure

Field	Type	Description
id	snowflake	The ID of the scheduled event
guild_id	snowflake	The ID of the guild the scheduled event belongs to
channel_id ²	?snowflake	The ID of the channel in which the scheduled event will be hosted
creator_id? ¹	?snowflake	The ID of the user that created the scheduled event
creator?	partial user object	The user that created the scheduled event
name	string	The name of the scheduled event (1-100 characters)
description?	?string	The description for the scheduled event (1-1000 characters)
scheduled_start_time	ISO8601 timestamp	When the scheduled event will start
scheduled_end_time ²	?ISO8601 timestamp	When the scheduled event will end
auto_start? ³	boolean	Whether the event should automatically start at the scheduled start time
privacy_level	integer	The privacy level of the scheduled event
status	integer	The status of the scheduled event
entity_type	integer	The type of scheduled event
entity_id	?snowflake	The ID of an entity associated with the scheduled event
entity_metadata ²	?entity metadata object	Additional metadata for the scheduled event
user_count? ⁴	integer	The number of users subscribed to the scheduled event
image?	?string	The cover image hash for the scheduled event
recurrence_rule	?recurrence rule object	The definition for how often this event should recur
guild_scheduled_event_exceptions	array[exception object]	Exceptions to the recurrence rule for this event

¹ 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.

³ Only included in Gateway events. See the automations section for more info on how to determine this manually.

⁴ Only included when fetched from the Get Guild Scheduled Events or Get Guild Scheduled Event endpoints with with_user_count set to true.

Example Guild Scheduled Event

{
  "id": "1059954443799498922",
  "guild_id": "1046920999469330512",
  "name": "Alien meetup",
  "description": "Aliens only!",
  "channel_id": null,
  "creator_id": "787017887877169173",
  "creator": {
    "id": "787017887877169173",
    "username": "dziurwa",
    "avatar": "cff3479a14360e4223f151eb8ad63dec",
    "discriminator": "0",
    "public_flags": 4194560,
    "banner": null,
    "accent_color": null,
    "global_name": "Dziurwa",
    "avatar_decoration_data": null,
    "primary_guild": null
  },
  "image": "4b07ee3046773e8f2c8be856a70bd1a7",
  "scheduled_start_time": "2023-12-31T23:00:00+00:00",
  "scheduled_end_time": "2024-01-01T23:00:00+00:00",
  "status": 1,
  "entity_type": 3,
  "entity_id": null,
  "recurrence_rule": null,
  "user_count": 7,
  "privacy_level": 2,
  "sku_ids": [],
  "guild_scheduled_event_exceptions": [],
  "entity_metadata": {
    "location": "somwhere in ocean"
  }
}

Guild Scheduled Event Entity Metadata

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

¹ Required for events with an entity_type of EXTERNAL.

Guild Scheduled Event Status

Value	Name	Description
1	SCHEDULED	The scheduled event has not started yet
2	ACTIVE	The scheduled event is currently active
3	COMPLETED ¹	The scheduled event has ended
4	CANCELED ¹	The scheduled event was canceled

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

Guild Scheduled Event Entity Type

Value	Name	Description
1	STAGE_INSTANCE	The scheduled event is in a stage channel
2	VOICE	The scheduled event is in a voice channel
3	EXTERNAL	The scheduled event is somewhere else™ not associated with Discord
4	PRIME_TIME	The scheduled event is a prime time event

Guild Scheduled Event Entity Type Validation

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

Entity Type	channel_id	entity_metadata	scheduled_end_time
STAGE_INSTANCE	required	null	-
VOICE	required	null	-
EXTERNAL	null	required with `location`	required

Guild Scheduled Event Recurrence Rule Object

Discord's recurrence rule is a subset of the behaviors defined in the iCalendar RFC and implemented using Python's dateutil rrule.

Guild Scheduled Event Recurrence Rule Structure

Field	Type	Description
start	ISO8601 timestamp	Starting time of the recurrence interval
end ¹	?ISO8601 timestamp	Ending time of the recurrence interval
frequency	integer	How often the event occurs
interval	integer	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[integer]	Specific days within a week for the event to recur on
by_n_weekday	?array[recurrence rule - n_weekday object]	Specific days within a specific week (1-5) to recur on
by_month	?array[integer]	Specific months to recur on
by_month_day	?array[integer]	Specific dates within a month to recur on
by_year_day ¹	?array[integer]	Specific days within a year to recur on (1-364)
count ¹	?integer	The total amount of times that the event is allowed to recur before stopping

¹ Cannot currently be set externally.

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

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 or WEEKLY)
when used in a daily event (frequency is DAILY)
- 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)
- by_weekday array currently can only be have 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)
by_n_weekday array currently can only have 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)
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`

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

Value	Name
0	YEARLY
1	MONTHLY
2	WEEKLY
3	DAILY

Guild Scheduled Event Recurrence Rule - Weekday

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

Guild Scheduled Event Recurrence Rule - N_Weekday Structure

Field	Type	Description
n	integer	The week to reoccur on (1-5)
day	integer	The day within the week to reoccur on

Guild Scheduled Event Recurrence Rule - Month

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

Guild Scheduled Event Exception Object

Represents an exception to the recurrence rule for a guild scheduled event.

Guild Scheduled Event Exception Structure

Field	Type	Description
event_id	snowflake	The ID of the scheduled event the exception is for
event_exception_id	snowflake	A snowflake representing when the scheduled event would have started without the exception
is_canceled	boolean	Whether the scheduled event will be skipped on this recurrence
scheduled_start_time	?ISO8601 timestamp	The scheduled event's modified start time for this recurrence
scheduled_end_time	?ISO8601 timestamp	The scheduled event's modified end time for this recurrence

Example Guild Scheduled Event Exception

{
  "event_id": "1341289071875461170",
  "event_exception_id": "2117779587072000000",
  "scheduled_start_time": "2030-02-18T00:01:00+00:00",
  "scheduled_end_time": null,
  "is_canceled": false
}

Guild Scheduled Event User Object

Represents a user's subscription to a guild scheduled event or override for a specific exception.

Guild Scheduled Event User Structure

Field	Type	Description
guild_scheduled_event_id	snowflake	The ID of the scheduled event the user subscribed to
guild_scheduled_event_exception_id?	snowflake	The ID of the specific exception this subscription is for, if any
response	integer	The user's response to the scheduled event
user_id	snowflake	The ID of the user that subscribed to the scheduled event
user? ¹	partial user object	The user that subscribed to the scheduled event
member? ¹	guild member object	Guild member data for the user in the scheduled event's guild, if any

¹ Only included when fetched from the Get Guild Scheduled Event Users endpoint.

Guild Scheduled Event User Response

Value	Name	Description
0	UNINTERESTED	User is not interested in the occurrence
1	INTERESTED	User is interested in the event or occurrence

Endpoints

Get User Guild Scheduled Events

GET/users/@me/scheduled-events

Returns an array of guild scheduled event user objects for the current user for a given guild.

Query String Params

Field	Type	Description
guild_ids	snowflake	The guild ID to get the subscribed scheduled events for

Get Guild Scheduled Events

GET/guilds/{guild.id}/scheduled-events

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

Query String Params

Field	Type	Description
with_user_count?	boolean	Whether to include the of users subscribed to each event (default false)

Get Guild Scheduled Event

GET/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}

Gets a guild scheduled event. Returns a guild scheduled event object.

Query String Params

Field	Type	Description
with_user_count?	boolean	Whether to include the of users subscribed to each event (default false)

Create Guild Scheduled Event

POST/guilds/{guild.id}/scheduled-events

Audit Log Reason

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

JSON Params

Field	Type	Description
channel_id? ¹	snowflake	The ID of the channel in which the scheduled event will be hosted
entity_metadata? ²	entity metadata	Additional metadata for the scheduled event
name	string	the name of the scheduled event
privacy_level	integer	The privacy level of the scheduled event
scheduled_start_time	ISO8601 timestamp	When the scheduled event will start
scheduled_end_time? ²	ISO8601 timestamp	When the scheduled event will end
description?	string	the description of the scheduled event
entity_type	integer	The entity type of the scheduled event
image?	image data	The cover image for the scheduled event
recurrence_rule?	?recurrence rule object	The definition for how often this event should recur

¹ Optional for events with an entity_type of EXTERNAL.

² Required for events with an entity_type of EXTERNAL.

Modify Guild Scheduled Event

PATCH/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}

Audit Log Reason

Modifies a guild scheduled event. Returns the modified guild scheduled event object on success. Fires a Guild Scheduled Event Update and optionally a Stage Instance Create Gateway event.

JSON Params

Field	Type	Description
channel_id? ¹	?snowflake	The ID of the channel in which the scheduled event will be hosted
entity_metadata?	?entity metadata	Additional metadata for the scheduled event
name?	string	The name of the scheduled event
privacy_level?	integer	The privacy level of the scheduled event
scheduled_start_time?	ISO8601 timestamp	When the scheduled event will start
scheduled_end_time? ¹	ISO8601 timestamp	When the scheduled event will end
description?	?string	the description of the scheduled event
entity_type? ¹	integer	The entity type of the scheduled event
status? ²	integer	The status of the scheduled event
image?	image data	The cover image for the scheduled event

¹ 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

² Only the following are valid status changes:

SCHEDULED --> ACTIVE
ACTIVE --> COMPLETED
SCHEDULED --> CANCELED

Delete Guild Scheduled Event

DELETE/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}

Audit Log Reason

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

Create Guild Scheduled Event Exception

POST/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/exceptions

Audit Log Reason

Creates an exception to the recurrence rule for a guild scheduled event. Returns a guild scheduled event exception object on success. Fires a Guild Scheduled Event Exception Create Gateway event.

JSON Params

Field	Type	Description
original_scheduled_start_time	ISO8601 timestamp	When the scheduled event would have started without the exception
is_canceled?	boolean	Whether the scheduled event will be skipped on this recurrence
scheduled_start_time?	?ISO8601 timestamp	The scheduled event's modified start time for this recurrence
scheduled_end_time?	?ISO8601 timestamp	The scheduled event's modified end time for this recurrence

Modify Guild Scheduled Event Exception

PATCH/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/{guild_scheduled_event_exception.id}

Audit Log Reason

Modifies an exception to the recurrence rule for a guild scheduled event. Returns the modified guild scheduled event exception object on success. Fires a Guild Scheduled Event Exception Create Gateway event.

JSON Params

Field	Type	Description
is_canceled?	boolean	Whether the scheduled event will be skipped on this recurrence
scheduled_start_time?	?ISO8601 timestamp	The scheduled event's modified start time for this recurrence
scheduled_end_time?	?ISO8601 timestamp	The scheduled event's modified end time for this recurrence

Delete Guild Scheduled Event Exception

DELETE/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/{guild_scheduled_event_exception.id}

Audit Log Reason

Deletes an exception to the recurrence rule for a guild scheduled event. Returns a 204 empty response on success. Fires a Guild Scheduled Event Exception Delete Gateway event.

Get Guild Scheduled Event User Count

GET/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/users/count

Returns the number of users subscribed to a guild scheduled event.

Query String Params

Field	Type	Description
guild_scheduled_event_exception_ids?	array[snowflake]	The IDs of the exceptions to return counts for (max 10)

Response Body

Field	Type	Description
guild_scheduled_event_count	integer	The number of users subscribed to the guild scheduled event
guild_scheduled_event_exception_counts	map[snowflake, integer]	The number of users subscribed to each exception

Example Response

{
  "guild_scheduled_event_count": 18,
  "guild_scheduled_event_exception_counts": {
    "1456059344486400000": 18
  }
}

Get Guild Scheduled Event Users

GET/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/users

Returns a list of users subscribed to a guild scheduled event.

Query String Params

Field	Type	Description
before?	snowflake	Get users before this user ID
after?	snowflake	Get users after this user ID
limit?	number	Max number of users to return (1-100, default 100)
with_member?	boolean	Whether to include possible guild member data (default false)
upgrade_response_type? ¹	boolean	Whether to return the new response body format (default false)

¹ This parameter is ignored for bots as they always receive the new response body format.

Response Body

When upgrade_response_type is set to true, the response is a list of guild scheduled event user objects.

Otherwise, the response looks like this:

Field	Type	Description
users	array[partial user object]	The users subscribed to the scheduled event, with an extra `guild_member` containing optional guild member data

Create Guild Scheduled Event User

PUT/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/users/@me

Subscribes the current user to a guild scheduled event. Returns a guild scheduled event user object on success. Fires a Guild Scheduled Event User Add Gateway event.

Delete Guild Scheduled Event User

DELETE/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/users/@me

Unsubscribes the current user from a guild scheduled event. Returns a 204 empty response on success. Fires a Guild Scheduled Event User Remove Gateway event.

Get Guild Scheduled Event Exception Users

GET/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/{guild_scheduled_event_exception.id}/users

Returns a list of guild scheduled event user objects subscribed to a specific guild scheduled event exception.

Query String Params

Field	Type	Description
before?	snowflake	Get users before this user ID
after?	snowflake	Get users after this user ID
limit?	number	Max number of users to return (1-100, default 100)
with_member?	boolean	Whether to include possible guild member data (default false)

Create Guild Scheduled Event Exception User

PUT/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/{guild_scheduled_event_exception.id}/users/@me

Overrides the user's subscription to a guild scheduled event for a specific exception. Returns a subscribed guild scheduled event user object on success. Fires a Guild Scheduled Event User Add Gateway event.

JSON Params

Field	Type	Description
response	integer	The user's response to the scheduled event exception

Delete Guild Scheduled Event Exception User

DELETE/guilds/{guild.id}/scheduled-events/{guild_scheduled_event.id}/{guild_scheduled_event_exception.id}/users/@me

Removes the user's subscription override for a specific exception. Returns a 204 empty response on success. Fires a Guild Scheduled Event User Remove Gateway event.

Guild Scheduled Event Status Update Automation

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 a status of ACTIVE and entity_type of 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 a status of ACTIVE and entity_type of 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.

MANAGE_EVENTS at the guild level or at least MANAGE_EVENTS for the channel_id associated with the event
MANAGE_CHANNELS
MUTE_MEMBERS
MOVE_MEMBERS

Read Permissions (GET)

VIEW_CHANNEL for channel_id associated with the event

Permissions to create an event with entity_type: `VOICE`

Write Permissions (CREATE / UPDATE)

MANAGE_EVENTS at the guild level or MANAGE_EVENTS for the channel_id associated with the event
VIEW_CHANNEL for channel_id associated with event
CONNECT for channel_id associated with event

Read Permissions (GET)

VIEW_CHANNEL for channel_id associated with the event

Permissions to create an event with entity_type: `EXTERNAL`

Write Permissions (CREATE / UPDATE)

MANAGE_EVENTS at the guild level

Read Permissions (GET)

No other permissions required