Stage Instance Resource

A stage instance holds information about a live stage. For more information on stages, see the channel object.

Definitions

Below are some definitions related to stages.

Liveness: A stage channel is considered live when there is an associated stage instance. Conversely, a stage channel is not live when there is no associated stage instance.
Speakers: A participant of a stage channel is a speaker when their voice state is not suppressed, and has no request_to_speak_timestamp.
Moderators: A member of the guild is a moderator of a stage channel if they have all of the following permissions:
- MANAGE_CHANNELS
- MUTE_MEMBERS
- MOVE_MEMBERS
Topic: This is the blurb that gets shown below the channel's name, among other places.
Public: A stage instance is public when it has a privacy_level of PUBLIC. While a guild has a public stage instance:
- Lurkers may join any stage channel with a public stage instance.
- Users in the stage can have the stage show in their activities.
- Invites to the stage channel will have the stage_instance field.

Auto Closing

When a stage channel has no speakers for a certain period of time (on the order of minutes) the stage instance will be automatically deleted.

Stage Instance Object

Stage Instance Structure

Field	Type	Description
id	snowflake	The ID of the stage instance
guild_id	snowflake	The guild ID of the associated stage channel
channel_id	snowflake	The ID of the associated stage channel
topic	string	The topic of the stage instance (1-120 characters)
privacy_level	integer	The privacy level of the stage instance
invite_code	?string	The invite code that can be used to join the stage channel, if the stage instance is public
discoverable_disabled (deprecated)	boolean	Whether or not stage Discovery is disabled
guild_scheduled_event_id	?snowflake	The ID of the scheduled event for this stage instance

Example Stage Instance

{
  "id": "840647391636226060",
  "guild_id": "197038439483310086",
  "channel_id": "733488538393510049",
  "topic": "Testing, Testing, 123",
  "privacy_level": 1,
  "discoverable_disabled": false,
  "guild_scheduled_event_id": "947656305244532806",
  "invite_code": "xdMaxHJqp8"
}

Create Stage Instance

POST/stage-instances

Audit Log Reason

Creates a new stage instance associated to a stage channel. Returns a stage instance object. Fires a Stage Instance Create and may fire an Invite Create Gateway event.

Requires the user to be a moderator of the stage channel.

JSON Params

Field	Type	Description
channel_id	snowflake	The ID of the stage channel
topic	string	The topic of the stage instance (1-120 characters)
privacy_level?	integer	The privacy level of the stage instance (default `GUILD_ONLY`)
guild_scheduled_event_id?	snowflake	The ID of the scheduled event for this stage instance
send_start_notification? ¹	boolean	Notify @everyone that a stage instance has started (default false)

¹ The stage moderator must have the MENTION_EVERYONE permission for this notification to be sent.

Endpoints

Get Stage Instance

GET/stage-instances/{channel.id}

Gets the stage instance associated with the stage channel, if it exists. Returns a stage instance object.

Modify Stage Instance

PATCH/stage-instances/{channel.id}

Audit Log Reason

Updates fields of an existing stage instance. Returns the updated stage instance object on success. Fires a Stage Instance Update Gateway event.

Requires the user to be a moderator of the stage channel.

JSON Params

Field	Type	Description
topic?	string	The topic of the stage instance (1-120 characters)
privacy_level?	integer	The privacy level of the stage instance

Delete Stage Instance

DELETE/stage-instances/{channel.id}

Audit Log Reason

Deletes the stage instance and associated invite. Returns a 204 empty response on success. Fires a Stage Instance Delete and may fire an Invite Delete Gateway event.

Requires the user to be a moderator of the stage channel.