Skip to main content
A Stage Instance holds information about a live stage.

​
Stage Instance Object

Stage Instance Structure
FieldTypeDescription
idsnowflakeThe id of this Stage instance
guild_idsnowflakeThe guild id of the associated Stage channel
channel_idsnowflakeThe id of the associated Stage channel
topicstringThe topic of the Stage instance (1-120 characters)
privacy_levelintegerThe privacy level of the Stage instance
discoverable_disabledbooleanWhether or not Stage Discovery is disabled (deprecated)
guild_scheduled_event_id?snowflakeThe id of the scheduled event for this Stage instance
Privacy Level
LevelValueDescription
PUBLIC1The Stage instance is visible publicly. (deprecated)
GUILD_ONLY2The 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
FieldTypeDescription
channel_idsnowflakeThe id of the Stage channel
topicstringThe topic of the Stage instance (1-120 characters)
privacy_level?integerThe privacy level of the Stage instance (default GUILD_ONLY)
send_start_notification? *booleanNotify @everyone that a Stage instance has started
guild_scheduled_event_id?snowflakeThe 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
FieldTypeDescription
privacy_level?integerThe 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.