Stage Instance Resource

Reference for Discord stage instance objects for managing live audio events.

A Stage Instance holds information about a live stage.

Stage Instance Object

Stage Instance Structure

Field	Type	Description
id	snowflake	The id of this 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
discoverable_disabled	boolean	Whether or not Stage Discovery is disabled (deprecated)
guild_scheduled_event_id	?snowflake	The id of the scheduled event for this Stage instance

Privacy Level

Level	Value	Description
PUBLIC	1	The Stage instance is visible publicly. (deprecated)
GUILD_ONLY	2	The Stage instance is visible to only guild members.

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

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:
  • 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.

Create Stage Instance

POST/stage-instances

Creates a new Stage instance associated to a Stage channel. Returns that Stage instance. Fires a Stage Instance Create Gateway event.

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

This endpoint supports the X-Audit-Log-Reason header.

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)
send_start_notification? *	boolean	Notify @everyone that a Stage instance has started
guild_scheduled_event_id?	snowflake	The guild scheduled event associated with this Stage instance

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

Get Stage Instance

GET/stage-instances/{channel.id}

Gets the stage instance associated with the Stage channel, if it exists.

Modify Stage Instance

PATCH/stage-instances/{channel.id}

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

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

This endpoint supports the X-Audit-Log-Reason header.

JSON Params

Field	Type	Description
privacy_level?	integer	The privacy level of the Stage instance

Delete Stage Instance

DELETE/stage-instances/{channel.id}

Deletes the Stage instance. Returns 204 No Content. Fires a Stage Instance Delete Gateway event.

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

This endpoint supports the X-Audit-Log-Reason header.