Skip to content

Commit 90b8e8c

Browse files
advaith1advaith1
authored
Document Soundboard (#6260)
1 parent e6cf4a9 commit 90b8e8c

File tree

7 files changed

+251
-27
lines changed

7 files changed

+251
-27
lines changed

‎docs/change_log/2024-00-20-soundboard-api.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Soundboard API"
3+
date: "2024-09-20"
4+
---
5+
6+
[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!

‎docs/resources/Audit_Log.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,9 @@ If no object is noted, there won't be a `changes` array in the entry, though oth
126126
| THREAD_UPDATE | 111 | Thread was updated | [Thread](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) |
127127
| THREAD_DELETE | 112 | Thread was deleted | [Thread](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) |
128128
| APPLICATION_COMMAND_PERMISSION_UPDATE | 121 | Permissions were updated for a command | [Command Permission](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-permissions-object-application-command-permissions-structure)\* |
129+
| SOUNDBOARD_SOUND_CREATE | 130 | Soundboard sound rule was created | [Soundboard Sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) |
130+
| SOUNDBOARD_SOUND_UPDATE | 131 | Soundboard sound rule was updated | [Soundboard Sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) |
131+
| SOUNDBOARD_SOUND_DELETE | 132 | Soundboard sound rule was deleted | [Soundboard Sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) |
129132
| AUTO_MODERATION_RULE_CREATE | 140 | Auto Moderation rule was created | [Auto Moderation Rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) |
130133
| AUTO_MODERATION_RULE_UPDATE | 141 | Auto Moderation rule was updated | [Auto Moderation Rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) |
131134
| AUTO_MODERATION_RULE_DELETE | 142 | Auto Moderation rule was deleted | [Auto Moderation Rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) |

‎docs/resources/Guild.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,7 @@ Guilds in Discord represent an isolated collection of users and channels, and ar
142142
| INVITES_DISABLED | guild has paused invites, preventing new users from joining |
143143
| INVITE_SPLASH | guild has access to set an invite splash background |
144144
| MEMBER_VERIFICATION_GATE_ENABLED | guild has enabled [Membership Screening](#DOCS_RESOURCES_GUILD/membership-screening-object) |
145+
| MORE_SOUNDBOARD | guild has increased custom soundboard sound slots |
145146
| MORE_STICKERS | guild has increased custom sticker slots |
146147
| NEWS | guild has access to create announcement channels |
147148
| PARTNERED | guild is partnered |
@@ -150,6 +151,7 @@ Guilds in Discord represent an isolated collection of users and channels, and ar
150151
| ROLE_ICONS | guild is able to set role icons |
151152
| ROLE_SUBSCRIPTIONS_AVAILABLE_FOR_PURCHASE | guild has role subscriptions that can be purchased |
152153
| ROLE_SUBSCRIPTIONS_ENABLED | guild has enabled role subscriptions |
154+
| SOUNDBOARD | guild has created soundboard sounds |
153155
| TICKETED_EVENTS_ENABLED | guild has enabled ticketed events |
154156
| VANITY_URL | guild has access to set a vanity URL |
155157
| VERIFIED | guild is verified |

‎docs/resources/Soundboard.md

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
sidebar_label: Soundboard
3+
---
4+
5+
# Soundboard Resource
6+
7+
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.
8+
9+
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.
10+
11+
Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds).
12+
13+
### Soundboard Sound Object
14+
15+
###### Soundboard Sound Structure
16+
17+
| Field | Type | Description |
18+
|------------|-------------------------------------------------|---------------------------------------------------------------------------|
19+
| name | string | the name of this sound |
20+
| sound_id | snowflake | the id of this sound |
21+
| volume | double | the volume of this sound, from 0 to 1 |
22+
| emoji_id | ?snowflake | the id of this sound's custom emoji |
23+
| emoji_name | ?string | the unicode character of this sound's standard emoji |
24+
| guild_id? | snowflake | the id of the guild this sound is in |
25+
| available | boolean | whether this sound can be used, may be false due to loss of Server Boosts |
26+
| user? | [user](#DOCS_RESOURCES_USER/user-object) object | the user who created this sound |
27+
28+
###### Example Default Soundboard Sound
29+
30+
```json
31+
{
32+
"name": "quack",
33+
"sound_id": "1",
34+
"volume": 1.0,
35+
"emoji_id": null,
36+
"emoji_name": "🦆",
37+
"available": true
38+
}
39+
```
40+
41+
###### Example Guild Soundboard Sound
42+
43+
```json
44+
{
45+
"name": "Yay",
46+
"sound_id": "1106714396018884649",
47+
"volume": 1,
48+
"emoji_id": "989193655938064464",
49+
"emoji_name": null,
50+
"guild_id": "613425648685547541",
51+
"available": true
52+
}
53+
```
54+
55+
### Sound Files
56+
57+
A soundboard sound can be retrieved in MP3 or Ogg format at the URL:
58+
59+
```
60+
https://cdn.discordapp.com/soundboard-sounds/{sound_id}
61+
```
62+
63+
## Send Soundboard Sound % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/send-soundboard-sound
64+
65+
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.
66+
67+
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.
68+
69+
###### JSON Params
70+
71+
| Field | Type | Description |
72+
|------------------|-----------|--------------------------------------------------------------------------------------------------|
73+
| sound_id | snowflake | the id of the soundboard sound to play |
74+
| source_guild_id? | snowflake | the id of the guild the soundboard sound is from, required to play sounds from different servers |
75+
76+
## List Default Soundboard Sounds % GET /soundboard-default-sounds
77+
78+
Returns an array of [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) objects that can be used by all users.
79+
80+
## List Guild Soundboard Sounds % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds
81+
82+
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.
83+
84+
###### Response Structure
85+
86+
| Field | Type |
87+
|-------|-----------------------------------------------------------------------------------------|
88+
| items | array of [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) objects |
89+
90+
## Get Guild Soundboard Sound % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds/{sound.id#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object}
91+
92+
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.
93+
94+
## Create Guild Soundboard Sound % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds
95+
96+
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.
97+
98+
> info
99+
> Soundboard sounds have a max file size of 512kb and a max duration of 5.2 seconds.
100+
101+
> info
102+
> This endpoint supports the `X-Audit-Log-Reason` header.
103+
104+
###### JSON Params
105+
106+
| Field | Type | Description |
107+
|-------------|------------|------------------------------------------------------------------------------------------------|
108+
| name | string | name of the soundboard sound (2-32 characters) |
109+
| sound | data uri | the mp3 or ogg sound data, base64 encoded, similar to [image data](#DOCS_REFERENCE/image-data) |
110+
| volume? | ?double | the volume of the soundboard sound, from 0 to 1, defaults to 1 |
111+
| emoji_id? | ?snowflake | the id of the custom emoji for the soundboard sound |
112+
| emoji_name? | ?string | the unicode character of a standard emoji for the soundboard sound |
113+
114+
## Modify Guild Soundboard Sound % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds/{sound.id#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object}
115+
116+
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.
117+
118+
> warn
119+
> All parameters to this endpoint are optional.
120+
121+
> info
122+
> This endpoint supports the `X-Audit-Log-Reason` header.
123+
124+
###### JSON Params
125+
126+
| Field | Type | Description |
127+
|------------|------------|--------------------------------------------------------------------|
128+
| name | string | name of the soundboard sound (2-32 characters) |
129+
| volume | ?double | the volume of the soundboard sound, from 0 to 1 |
130+
| emoji_id | ?snowflake | the id of the custom emoji for the soundboard sound |
131+
| emoji_name | ?string | the unicode character of a standard emoji for the soundboard sound |
132+
133+
## Delete Guild Soundboard Sound % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds/{sound.id#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object}
134+
135+
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.
136+
137+
> info
138+
> This endpoint supports the `X-Audit-Log-Reason` header.

‎docs/topics/Gateway.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -320,9 +320,13 @@ GUILD_MODERATION (1 << 2)
320320
- GUILD_BAN_ADD
321321
- GUILD_BAN_REMOVE
322322
323-
GUILD_EMOJIS_AND_STICKERS (1 << 3)
323+
GUILD_EXPRESSIONS (1 << 3)
324324
- GUILD_EMOJIS_UPDATE
325325
- GUILD_STICKERS_UPDATE
326+
- GUILD_SOUNDBOARD_SOUND_CREATE
327+
- GUILD_SOUNDBOARD_SOUND_UPDATE
328+
- GUILD_SOUNDBOARD_SOUND_DELETE
329+
- GUILD_SOUNDBOARD_SOUNDS_UPDATE
326330
327331
GUILD_INTEGRATIONS (1 << 4)
328332
- GUILD_INTEGRATIONS_UPDATE

0 commit comments

Comments
 (0)