Document Soundboard #6260
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| --- | ||
| title: "Soundboard API" | ||
| date: "2024-09-20" | ||
| --- | ||
|
|
||
| [Soundboard](#DOCS_RESOURCES_SOUNDBOARD) is now available in the API! Apps can now [get](#DOCS_RESOURCES_SOUNDBOARD/list-default-soundboard-sounds) soundboard sounds, [modify](#DOCS_RESOURCES_SOUNDBOARD/modify-guild-soundboard-sound) them, [send](#DOCS_RESOURCES_SOUNDBOARD/send-soundboard-sound) them in voice channels, and listen to other users playing them! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,138 @@ | ||
| --- | ||
| sidebar_label: Soundboard | ||
| --- | ||
|
|
||
| # Soundboard Resource | ||
|
|
||
| Users can play soundboard sounds in voice channels, triggering a [Voice Channel Effect Send](#DOCS_TOPICS_GATEWAY_EVENTS/voice-channel-effect-send) Gateway event for users connected to the voice channel. | ||
|
|
||
| There is a set of [default sounds](#DOCS_RESOURCES_SOUNDBOARD/list-default-soundboard-sounds) available to all users. Soundboard sounds can also be [created in a guild](#DOCS_RESOURCES_SOUNDBOARD/create-guild-soundboard-sound); users will be able to use the sounds in the guild, and Nitro subscribers can use them in all guilds. | ||
|
|
||
| Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds). | ||
|
|
||
| ### Soundboard Sound Object | ||
|
|
||
| ###### Soundboard Sound Structure | ||
|
|
||
| | Field | Type | Description | | ||
| |------------|-------------------------------------------------|---------------------------------------------------------------------------| | ||
| | name | string | the name of this sound | | ||
| | sound_id | snowflake | the id of this sound | | ||
| | volume | double | the volume of this sound, from 0 to 1 | | ||
| | emoji_id | ?snowflake | the id of this sound's custom emoji | | ||
| | emoji_name | ?string | the unicode character of this sound's standard emoji | | ||
| | guild_id? | snowflake | the id of the guild this sound is in | | ||
| | available | boolean | whether this sound can be used, may be false due to loss of Server Boosts | | ||
| | user? | [user](#DOCS_RESOURCES_USER/user-object) object | the user who created this sound | | ||
|
|
||
| ###### Example Default Soundboard Sound | ||
|
|
||
| ```json | ||
| { | ||
| "name": "quack", | ||
| "sound_id": "1", | ||
| "volume": 1.0, | ||
| "emoji_id": null, | ||
| "emoji_name": "🦆", | ||
| "available": true | ||
| } | ||
| ``` | ||
|
|
||
| ###### Example Guild Soundboard Sound | ||
|
|
||
| ```json | ||
| { | ||
| "name": "Yay", | ||
| "sound_id": "1106714396018884649", | ||
| "volume": 1, | ||
| "emoji_id": "989193655938064464", | ||
| "emoji_name": null, | ||
| "guild_id": "613425648685547541", | ||
| "available": true | ||
| } | ||
| ``` | ||
|
|
||
| ### Sound Files | ||
|
There was a problem hiding this comment. maybe that could be integrated into the reference section somehow, since that's the only place where CDN endpoints are currently listed... |
||
|
|
||
| A soundboard sound can be retrieved in MP3 or Ogg format at the URL: | ||
|
|
||
| ``` | ||
| https://cdn.discordapp.com/soundboard-sounds/{sound_id} | ||
| ``` | ||
|
|
||
| ## Send Soundboard Sound % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/send-soundboard-sound | ||
|
|
||
| Send a soundboard sound to a voice channel the user is connected to. Fires a [Voice Channel Effect Send](#DOCS_TOPICS_GATEWAY_EVENTS/voice-channel-effect-send) Gateway event. | ||
|
|
||
| Requires the `SPEAK` and `USE_SOUNDBOARD` permissions, and also the `USE_EXTERNAL_SOUNDS` permission if the sound is from a different server. Additionally, requires the user to be connected to the voice channel, having a [voice state](#DOCS_RESOURCES_VOICE/voice-state-object) without `deaf`, `self_deaf`, `mute`, or `suppress` enabled. | ||
|
|
||
| ###### JSON Params | ||
|
|
||
| | Field | Type | Description | | ||
| |------------------|-----------|--------------------------------------------------------------------------------------------------| | ||
| | sound_id | snowflake | the id of the soundboard sound to play | | ||
| | source_guild_id? | snowflake | the id of the guild the soundboard sound is from, required to play sounds from different servers | | ||
|
|
||
| ## List Default Soundboard Sounds % GET /soundboard-default-sounds | ||
|
|
||
| Returns an array of [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) objects that can be used by all users. | ||
|
|
||
| ## List Guild Soundboard Sounds % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds | ||
|
|
||
| Returns a list of the guild's soundboard sounds. Includes `user` fields if the bot has the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. | ||
advaith1 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ###### Response Structure | ||
|
|
||
| | Field | Type | | ||
| |-------|-----------------------------------------------------------------------------------------| | ||
| | items | array of [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) objects | | ||
|
|
||
| ## Get Guild Soundboard Sound % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds/{sound.id#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object} | ||
|
|
||
| Returns a [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) object for the given sound id. Includes the `user` field if the bot has the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. | ||
|
|
||
| ## Create Guild Soundboard Sound % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds | ||
|
|
||
| Create a new soundboard sound for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) object on success. Fires a [Guild Soundboard Sound Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-create) Gateway event. | ||
|
|
||
| > info | ||
| > Soundboard sounds have a max file size of 512kb and a max duration of 5.2 seconds. | ||
|
|
||
| > info | ||
| > This endpoint supports the `X-Audit-Log-Reason` header. | ||
|
|
||
| ###### JSON Params | ||
|
|
||
| | Field | Type | Description | | ||
| |-------------|------------|------------------------------------------------------------------------------------------------| | ||
| | name | string | name of the soundboard sound (2-32 characters) | | ||
| | sound | data uri | the mp3 or ogg sound data, base64 encoded, similar to [image data](#DOCS_REFERENCE/image-data) | | ||
| | volume? | ?double | the volume of the soundboard sound, from 0 to 1, defaults to 1 | | ||
| | emoji_id? | ?snowflake | the id of the custom emoji for the soundboard sound | | ||
| | emoji_name? | ?string | the unicode character of a standard emoji for the soundboard sound | | ||
|
|
||
| ## Modify Guild Soundboard Sound % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds/{sound.id#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object} | ||
|
|
||
| Modify the given soundboard sound. For sounds created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other sounds, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) object on success. Fires a [Guild Soundboard Sound Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-update) Gateway event. | ||
|
|
||
| > warn | ||
| > All parameters to this endpoint are optional. | ||
|
|
||
| > info | ||
| > This endpoint supports the `X-Audit-Log-Reason` header. | ||
|
|
||
| ###### JSON Params | ||
|
|
||
| | Field | Type | Description | | ||
| |------------|------------|--------------------------------------------------------------------| | ||
| | name | string | name of the soundboard sound (2-32 characters) | | ||
| | volume | ?double | the volume of the soundboard sound, from 0 to 1 | | ||
| | emoji_id | ?snowflake | the id of the custom emoji for the soundboard sound | | ||
| | emoji_name | ?string | the unicode character of a standard emoji for the soundboard sound | | ||
|
|
||
| ## Delete Guild Soundboard Sound % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds/{sound.id#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object} | ||
|
|
||
| Delete the given soundboard sound. For sounds created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other sounds, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Soundboard Sound Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-delete) Gateway event. | ||
|
|
||
| > info | ||
| > This endpoint supports the `X-Audit-Log-Reason` header. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
why is it
sound_idinstead ofidlike for other snowflake objects?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
there used to be an
idfield, they got rid of it and perhaps didn't see a point in breaking and changing the name