Eventos programados

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

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

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

² See field requirements by entity type to understand the relationship between and the following fields: , , and .

³ 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 set to .

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

Guild Scheduled Event Status

Value

Name

Description

SCHEDULED

The scheduled event has not started yet

ACTIVE

The scheduled event is currently active

COMPLETED ¹

The scheduled event has ended

CANCELED ¹

The scheduled event was canceled

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

Guild Scheduled Event Entity Type

Value

Name

Description

STAGE_INSTANCE

The scheduled event is in a stage channel

VOICE

The scheduled event is in a voice channel

EXTERNAL

The scheduled event is somewhere else™ not associated with Discord

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

The following combinations are mutually exclusive

Only valid for daily and weekly events ( of or )
when used in a daily event ( is )
- The values present in the event must be a "known set" of weekdays.
- The following are current allowed "sets"
  - Monday - Friday ()
  - Tuesday - Saturday ()
  - Sunday - Thursday ()
  - Friday & Saturday ()
  - Saturday & Sunday ()
  - Sunday & Monday ()
when used in a weekly event ( is )
- array currently can only be have length of
  - 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 of
- Also, see below for "every-other" week information

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

and

Only valid for annual event ( is )
both and must be provided
both and arrays must have a length of
- (i.e. you can only set a single date for annual events)

can only be set to a value other than when is set to

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

ExamplesSimple examples of some common Recurrent Rules

Every weekday

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

Every Wednesday

frequency = 2; // Frequency.WEEKLYinterval = 1;by_weekday = [2]; // [Weekday.WEDNESDAY]

Every other Wednesday

frequency = 2; // Frequency.WEEKLYinterval = 2;by_weekday = [2]; // [Weekday.WEDNESDAY]

Monthly on the fourth Wednesday

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

Annually on July 24

frequency = 0; // Frequency.YEARLYinterval = 1;by_month = [7]; // [Month.JULY]by_month_day = [24];

Guild Scheduled Event Recurrence Rule - Frequency

Value

Name

YEARLY

MONTHLY

WEEKLY

DAILY

Guild Scheduled Event Recurrence Rule - Weekday

Value

Name

MONDAY

TUESDAY

WEDNESDAY

THURSDAY

FRIDAY

SATURDAY

SUNDAY

Guild Scheduled Event Recurrence Rule - N_Weekday Structure

Field

Type

Description

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

JANUARY

FEBRUARY

MARCH

APRIL

MAY

JUNE

JULY

AUGUST

SEPTEMBER

OCTOBER

NOVEMBER

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

UNINTERESTED

User is not interested in the occurrence

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

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

² Required for events with an of .

Modify Guild Scheduled Event

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

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

is required and must be set to
with a field must be provided
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}

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

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}

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}

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 is set to , 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 extracontaining 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 of and of has no users connected to the stage channel for a certain period of time (on the order of minutes), the event will be automatically set to .

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 of and of has no users connected to the voice channel for a certain period of time (on the order of minutes), the event will be automatically set to .

An external event will automatically begin at its scheduled start time

An event with an of at its will automatically have set to .

An external event will automatically end at its scheduled end time

An event with an of at its will automatically have set to .

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

Any event with a of after a certain time interval (on the order of hours) beyond its will have its automatically set to .