Voice Resource

Voice resources are used to interact with voice in Discord. For more information on connecting to voice, see the Voice Connections topic.

Voice State Object

Used to represent a user's voice connection status.

Voice State Structure
FieldTypeDescription
guild_id? 1?snowflakeThe guild ID this voice state is for
channel_id?snowflakeThe channel ID this user is connected to
user_idsnowflakeThe user ID this voice state is for
member? 1guild member objectThe guild member this voice state is for
session_idstringThe session ID this voice state is from
deafbooleanWhether this user is deafened by the guild, if any
mutebooleanWhether this user is muted by the guild, if any
self_deafbooleanWhether this user is locally deafened
self_mutebooleanWhether this user is locally muted
self_stream?booleanWhether this user is streaming using "Go Live"
self_videobooleanWhether this user's camera is enabled
suppressbooleanWhether this user's permission to speak is denied
request_to_speak_timestamp?ISO8601 timestampThe time at which the user requested to speak

1 Omitted in the Gateway guild object.

Example Voice State
{
  "channel_id": "157733188964188161",
  "user_id": "80351110224678912",
  "session_id": "90326bd25d71d39b9ef95b299e3872ff",
  "deaf": false,
  "mute": false,
  "self_deaf": false,
  "self_mute": true,
  "suppress": false,
  "request_to_speak_timestamp": "2021-03-31T18:45:31.297561+00:00"
}

Voice Region Object

Voice Region Structure
FieldTypeDescription
idstringThe unique ID for the region
namestringThe name of the region
optimalbooleanWhether this is the closest to the current user's client
deprecatedbooleanWhether this is a deprecated voice region (avoid switching to these)
custombooleanWhether this is a custom voice region (used for events, etc.)

Endpoints

Get Voice Regions

GET/voice/regions

Returns an array of voice region objects that can be used when setting a voice channel's rtc_region.

Get Guild Voice Regions

GET/guilds/{guild.id}/regions

Returns a list of voice region objects that can be used when setting a voice channel's rtc_region. Unlike the similar Get Voice Regions route, this returns VIP servers when the guild is VIP-enabled.

Modify Current User Voice State

PATCH/guilds/{guild.id}/voice-states/@me

Updates the current user's voice state in the given guild ID. Returns a 204 empty response on success. Fires a Voice State Update Gateway event.

JSON Params
FieldTypeDescription
channel_id?snowflakeThe ID of the channel the user is currently in
suppress?booleanWhether the user is suppressed in the channel
request_to_speak_timestamp??ISO8601 timestampThe time at which the user requested to speak
Caveats

There are currently several caveats for this endpoint:

  • channel_id must point to a stage channel
  • Current user must already have joined channel_id
  • You must have the MUTE_MEMBERS permission to unsuppress yourself; you can always suppress yourself
  • You must have the REQUEST_TO_SPEAK permission to request to speak; you can always clear your own request to speak
  • You can only set request_to_speak_timestamp to the present or a future time

Modify User Voice State

PATCH/guilds/{guild.id}/voice-states/{user.id}

Updates another user's voice state in the given guild ID. Returns a 204 empty response on success. Fires a Voice State Update Gateway event.

JSON Params
FieldTypeDescription
channel_idsnowflakeThe ID of the channel the user is currently in
suppress?booleanWhether the user is suppressed in the channel
Caveats

There are currently several caveats for this endpoint:

  • channel_id must point to a stage channel
  • Target user must already have joined channel_id
  • You must have the MUTE_MEMBERS permission
  • When unsuppressed, user accounts will have their request_to_speak_timestamp set to the current time; bot users will not
  • When suppressed, the user will have their request_to_speak_timestamp removed

Send Voice Channel Effect

POST/channels/{channel.id}/voice-channel-effects

Sends a voice channel effect to a voice channel. Returns a 204 empty response on success. Fires a Voice Channel Effect Send Gateway event.

JSON Params
FieldTypeDescription
animation_type??integerThe type of emoji animation, if applicable (default BASIC)
animation_id??integerThe ID of the emoji animation (0-20, default 0)
emoji_id??snowflakeThe ID of the custom emoji to send
emoji_name??stringThe emoji name or unicode character of the emoji to send
Voice Channel Effect Animation Type
ValueNameDescription
0PREMIUMA fun animation, requires a premium (Nitro) subscription
1BASICThe standard animation

Get Stream Preview

GET/streams/{stream_key}/preview

Returns a URL to a stream preview for the given stream key. Requires the CONNECT permission in the stream's channel.

Response Structure
FieldTypeDescription
urlstringThe CDN URL to the stream preview

Upload Stream Preview

POST/streams/{stream_key}/preview

Uploads a stream preview for the given stream key. User must be the owner of the stream. Returns a 204 empty response on success.

JSON Params
FieldTypeDescription
thumbnailimage dataThe stream preview image

Broadcast Stream Notification

POST/streams/{stream_key}/notify

Broadcasts a stream notification to all friends of the current user that are in the same guild as the stream and have stream notifications enabled. User must be the owner of the stream and must be streaming in a guild. Returns a 204 empty response on success.