Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document Soundboard #6260

Merged
merged 23 commits into from
Sep 20, 2024
Merged

Document Soundboard #6260

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
b8f501e
Document Soundboard
advaith1 Jun 28, 2023
024e9f1
typo
advaith1 Jun 28, 2023
c08c6a9
fix guild_ids desc
advaith1 Jun 28, 2023
d99a5c1
Merge branch 'main' into soundboard
advaith1 May 15, 2024
8aef30a
update table formatting
advaith1 May 15, 2024
ea41d44
updates
advaith1 May 16, 2024
e78e753
add audit log events
advaith1 May 16, 2024
00d36a9
remove deprecated id field
advaith1 Jul 26, 2024
f218e93
remove required column
advaith1 Jul 26, 2024
ec86562
remove user_id and make available required
advaith1 Jul 29, 2024
8e18095
-
advaith1 Jul 29, 2024
8b05cc6
updates
advaith1 Aug 15, 2024
6a61661
Merge branch 'main' into pr/6260
advaith1 Aug 15, 2024
4c2c182
changelog
advaith1 Aug 15, 2024
292f14f
fix links
advaith1 Aug 15, 2024
ea5fd67
fix get permissions
advaith1 Aug 17, 2024
1b89fe9
Merge branch 'main' into pr/6260
advaith1 Aug 26, 2024
7359836
link to vc effect event
advaith1 Aug 26, 2024
5a13333
constants
advaith1 Aug 31, 2024
3c61875
re-add changelog
advaith1 Aug 31, 2024
451010c
fix link again
advaith1 Aug 31, 2024
f4c5ff3
fixes and examples
advaith1 Sep 20, 2024
8069f6a
delete extra line
advaith1 Sep 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/resources/Audit_Log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,9 @@ If no object is noted, there won't be a `changes` array in the entry, though oth
| THREAD_UPDATE | 111 | Thread was updated | [Thread](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) |
| THREAD_DELETE | 112 | Thread was deleted | [Thread](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) |
| 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)\* |
| SOUNDBOARD_SOUND_CREATE | 130 | Soundboard sound rule was created | [Soundboard Sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) |
| SOUNDBOARD_SOUND_UPDATE | 131 | Soundboard sound rule was updated | [Soundboard Sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) |
| SOUNDBOARD_SOUND_DELETE | 132 | Soundboard sound rule was deleted | [Soundboard Sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) |
| AUTO_MODERATION_RULE_CREATE | 140 | Auto Moderation rule was created | [Auto Moderation Rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) |
| AUTO_MODERATION_RULE_UPDATE | 141 | Auto Moderation rule was updated | [Auto Moderation Rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) |
| AUTO_MODERATION_RULE_DELETE | 142 | Auto Moderation rule was deleted | [Auto Moderation Rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) |
Expand Down
1 change: 1 addition & 0 deletions docs/resources/Guild.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@ Guilds in Discord represent an isolated collection of users and channels, and ar
| ROLE_ICONS | guild is able to set role icons |
| ROLE_SUBSCRIPTIONS_AVAILABLE_FOR_PURCHASE | guild has role subscriptions that can be purchased |
| ROLE_SUBSCRIPTIONS_ENABLED | guild has enabled role subscriptions |
| SOUNDBOARD | guild has created soundboard sounds |
| TICKETED_EVENTS_ENABLED | guild has enabled ticketed events |
| VANITY_URL | guild has access to set a vanity URL |
| VERIFIED | guild is verified |
Expand Down
81 changes: 81 additions & 0 deletions docs/resources/Soundboard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# Soundboard Resource

Users can play soundboard sounds in voice channels, triggering a Voice Channel Effect Send Gateway event for users connected to the voice channel. Bots cannot play soundboard sounds. Soundboard use is controlled by the `USE_SOUNDBOARD` and `USE_EXTERNAL_SOUNDS` [permissions](#DOCS_TOPICS_PERMISSIONS).
advaith1 marked this conversation as resolved.
Show resolved Hide resolved

There is a set of [default sounds](#DOCS_RESOURCES_SOUNDBOARD/list-soundboard-default-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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
There is a set of [default sounds](#DOCS_RESOURCES_SOUNDBOARD/list-soundboard-default-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.
There is a set of [default sounds](#DOCS_RESOURCES_SOUNDBOARD/list-soundboard-default-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 this guild, and Nitro subscribers can use them in any guild.


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 |
| user_id | snowflake | the id of the user who created this sound |
| available? | boolean | whether this sound can be used (for guild sounds), may be false due to loss of Server Boosts |
| user? | [user](#DOCS_RESOURCES_USER/user-object) object | the user who created this sound |

### Sound Files
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 format at the URL:

```
https://cdn.discordapp.com/soundboard-sounds/{sound_id}
```

## List Soundboard Default 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.

## 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 `MANAGE_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 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. 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, but the volume and emoji will be cleared if they are not included.

> 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, 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 |

## 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. 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.
Loading