Guild Scheduled Event Resource

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

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

Example Guild Scheduled Event

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

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

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 User Object

Guild Scheduled Event User Structure

Field	Type	Description
guild_scheduled_event_id	snowflake	The ID of the scheduled event the user subscribed to
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

Subscribed Guild Scheduled Event User Object

Subscribed Guild Scheduled Event User Structure

Field	Type	Description
guild_scheduled_event_id	snowflake	The ID of the scheduled event the user subscribed to
user_id	snowflake	The ID of the user that subscribed to the scheduled event

Endpoints

Get User Guild Scheduled Events

GET/users/@me/scheduled-events

Returns an array of subscribed 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 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

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

Get Guild Scheduled Event Users

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

Gets 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)

Response Body

Field	Type	Description
users	array[partial user object]	The users subscribed to the scheduled event, with an extra `guild_member` containing 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 subscribed 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.

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