From b8f501e5f651865cce13f983a108e742b70558e5 Mon Sep 17 00:00:00 2001 From: advaith Date: Tue, 27 Jun 2023 23:15:22 -0700 Subject: [PATCH 01/20] Document Soundboard --- docs/resources/Guild.md | 1 + docs/resources/Soundboard.md | 90 +++++++++++++++++++++++++ docs/topics/Gateway_Events.md | 78 +++++++++++++++++---- docs/topics/Opcodes_and_Status_Codes.md | 30 +++++---- 4 files changed, 173 insertions(+), 26 deletions(-) create mode 100644 docs/resources/Soundboard.md diff --git a/docs/resources/Guild.md b/docs/resources/Guild.md index 12ff1c0ca0..50442bc5db 100644 --- a/docs/resources/Guild.md +++ b/docs/resources/Guild.md @@ -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 | diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md new file mode 100644 index 0000000000..6146fc7c43 --- /dev/null +++ b/docs/resources/Soundboard.md @@ -0,0 +1,90 @@ +# 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). + +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. + +Soundboard sounds in a set of guilds can be retreived 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 | +| 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 | +| override_path | ?string | the filename of this sound (for default sounds) | +| 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 + +###### Base URL + +``` +https://cdn.discordapp.com/ +``` + +###### CDN Endpoints + +| Type | Path | +| ------------------------ | --------------------------------------------- | +| Soundboard Sound | soundboard-sounds/sound_id | +| Soundboard Default Sound | soundboard-default-sounds/sound_override_path | + +## 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. diff --git a/docs/topics/Gateway_Events.md b/docs/topics/Gateway_Events.md index 20b4ffed0f..27a236fd71 100644 --- a/docs/topics/Gateway_Events.md +++ b/docs/topics/Gateway_Events.md @@ -49,14 +49,15 @@ Send events are Gateway events encapsulated in an [event payload](#DOCS_TOPICS_G > info > Previously, Gateway send events were labeled as commands -| Name | Description | -| -------------------------------------------------------------------------- | --------------------------------------------------------- | -| [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) | Triggers the initial handshake with the gateway | -| [Resume](#DOCS_TOPICS_GATEWAY_EVENTS/resume) | Resumes a dropped gateway connection | -| [Heartbeat](#DOCS_TOPICS_GATEWAY_EVENTS/heartbeat) | Maintains an active gateway connection | -| [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) | Requests members for a guild | -| [Update Voice State](#DOCS_TOPICS_GATEWAY_EVENTS/update-voice-state) | Joins, moves, or disconnects the app from a voice channel | -| [Update Presence](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence) | Updates an app's presence | +| Name | Description | +| ---------------------------------------------------------------------------------- | --------------------------------------------------------- | +| [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) | Triggers the initial handshake with the gateway | +| [Resume](#DOCS_TOPICS_GATEWAY_EVENTS/resume) | Resumes a dropped gateway connection | +| [Heartbeat](#DOCS_TOPICS_GATEWAY_EVENTS/heartbeat) | Maintains an active gateway connection | +| [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) | Requests members for a guild | +| [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds) | Requests soundboard sounds in a set of guilds | +| [Update Voice State](#DOCS_TOPICS_GATEWAY_EVENTS/update-voice-state) | Joins, moves, or disconnects the app from a voice channel | +| [Update Presence](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence) | Updates an app's presence | #### Identify @@ -199,6 +200,27 @@ Due to our privacy and infrastructural concerns with this feature, there are som } ``` +#### Request Soundboard Sounds + +Used to request soundboard sounds for a list of guilds. The server will send [Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/soundboard-sounds) events for each guild in response. + +###### Request Soundboard Sounds Structure + +| Field | Type | Description | Required | +| ---------- | ------------------- | --------------------------------------------- | -------- | +| guild_ids | array of snowflakes | ID of the guilds to get soundboard sounds for | true | + +###### Example Request Soundboard Sounds + +```json +{ + "op": 31, + "d": { + "guild_ids": ["613425648685547541", "81384788765712384"] + } +} +``` + #### Update Voice State Sent when a client wants to join, move, or disconnect from a voice channel. @@ -745,19 +767,19 @@ Sent when a guild role is deleted. | guild_id | snowflake | ID of the guild | | role_id | snowflake | ID of the role | -### Guild Scheduled Event Create +#### Guild Scheduled Event Create Sent when a guild scheduled event is created. The inner payload is a [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object. -### Guild Scheduled Event Update +#### Guild Scheduled Event Update Sent when a guild scheduled event is updated. The inner payload is a [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object. -### Guild Scheduled Event Delete +#### Guild Scheduled Event Delete Sent when a guild scheduled event is deleted. The inner payload is a [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object. -### Guild Scheduled Event User Add +#### Guild Scheduled Event User Add Sent when a user has subscribed to a guild scheduled event. @@ -769,7 +791,7 @@ Sent when a user has subscribed to a guild scheduled event. | user_id | snowflake | ID of the user | | guild_id | snowflake | ID of the guild | -### Guild Scheduled Event User Remove +#### Guild Scheduled Event User Remove Sent when a user has unsubscribed from a guild scheduled event. @@ -781,6 +803,36 @@ Sent when a user has unsubscribed from a guild scheduled event. | user_id | snowflake | ID of the user | | guild_id | snowflake | ID of the guild | +#### Guild Soundboard Sound Create + +Sent when a guild soundboard sound is created. The inner payload is a [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) object. + +#### Guild Soundboard Sound Update + +Sent when a guild soundboard sound is updated. The inner payload is a [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) object. + +#### Guild Soundboard Sound Delete + +Sent when a guild soundboard sound is deleted. + +###### Guild Soundboard Sound Delete Event Fields + +| Field | Type | Description | +| -------- | --------- | -------------------------------- | +| sound_id | snowflake | ID of the sound that was deleted | +| guild_id | snowflake | ID of the guild the sound was in | + +#### Soundboard Sounds + +Includes a guild's list of soundboard sounds. Sent in response to [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds). + +###### Soundboard Sounds Event Fields + +| Field | Type | Description | +| ----------------- | --------------------------------------------------------------------------------------- | ----------------------------- | +| soundboard_sounds | array of [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) objects | The guild's soundboard sounds | +| guild_id | snowflake | ID of the guild | + ### Integrations #### Integration Create diff --git a/docs/topics/Opcodes_and_Status_Codes.md b/docs/topics/Opcodes_and_Status_Codes.md index f709f65a2d..b6d2a3bf0f 100644 --- a/docs/topics/Opcodes_and_Status_Codes.md +++ b/docs/topics/Opcodes_and_Status_Codes.md @@ -6,19 +6,20 @@ All gateway events in Discord are tagged with an opcode that denotes the payload ###### Gateway Opcodes -| Code | Name | Client Action | Description | -|------|-----------------------|---------------|-----------------------------------------------------------------------------------------| -| 0 | Dispatch | Receive | An event was dispatched. | -| 1 | Heartbeat | Send/Receive | Fired periodically by the client to keep the connection alive. | -| 2 | Identify | Send | Starts a new session during the initial handshake. | -| 3 | Presence Update | Send | Update the client's presence. | -| 4 | Voice State Update | Send | Used to join/leave or move between voice channels. | -| 6 | Resume | Send | Resume a previous session that was disconnected. | -| 7 | Reconnect | Receive | You should attempt to reconnect and resume immediately. | -| 8 | Request Guild Members | Send | Request information about offline guild members in a large guild. | -| 9 | Invalid Session | Receive | The session has been invalidated. You should reconnect and identify/resume accordingly. | -| 10 | Hello | Receive | Sent immediately after connecting, contains the `heartbeat_interval` to use. | -| 11 | Heartbeat ACK | Receive | Sent in response to receiving a heartbeat to acknowledge that it has been received. | +| Code | Name | Client Action | Description | +|------|---------------------------|---------------|-----------------------------------------------------------------------------------------| +| 0 | Dispatch | Receive | An event was dispatched. | +| 1 | Heartbeat | Send/Receive | Fired periodically by the client to keep the connection alive. | +| 2 | Identify | Send | Starts a new session during the initial handshake. | +| 3 | Presence Update | Send | Update the client's presence. | +| 4 | Voice State Update | Send | Used to join/leave or move between voice channels. | +| 6 | Resume | Send | Resume a previous session that was disconnected. | +| 7 | Reconnect | Receive | You should attempt to reconnect and resume immediately. | +| 8 | Request Guild Members | Send | Request information about offline guild members in a large guild. | +| 9 | Invalid Session | Receive | The session has been invalidated. You should reconnect and identify/resume accordingly. | +| 10 | Hello | Receive | Sent immediately after connecting, contains the `heartbeat_interval` to use. | +| 11 | Heartbeat ACK | Receive | Sent in response to receiving a heartbeat to acknowledge that it has been received. | +| 31 | Request Soundboard Sounds | Send | Request information about soundboard sounds in a set of guilds. | ###### Gateway Close Event Codes @@ -126,6 +127,7 @@ Along with the HTTP error code, our API can also return more detailed error code | 10015 | Unknown webhook | | 10016 | Unknown webhook service | | 10020 | Unknown session | +| 10021 | Unknown Asset | | 10026 | Unknown ban | | 10027 | Unknown SKU | | 10028 | Unknown Store Listing | @@ -265,6 +267,8 @@ Along with the HTTP error code, our API can also return more detailed error code | 50097 | This server needs monetization enabled in order to perform this action | | 50101 | This server needs more boosts to perform this action | | 50109 | The request body contains invalid JSON. | +| 50110 | The provided file is invalid. | +| 50124 | The provided file duration exceeds maximum of 5.2 seconds. | | 50131 | Owner cannot be pending member | | 50132 | Ownership cannot be transferred to a bot user | | 50138 | Failed to resize asset below the maximum size: 262144 | From 024e9f125a85be65ef6a8bc89ac83efaa6f3b6e9 Mon Sep 17 00:00:00 2001 From: advaith Date: Wed, 28 Jun 2023 02:26:16 -0700 Subject: [PATCH 02/20] typo Co-authored-by: Valle --- docs/resources/Soundboard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index 6146fc7c43..e796765446 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -4,7 +4,7 @@ Users can play soundboard sounds in voice channels, triggering a Voice Channel E 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. -Soundboard sounds in a set of guilds can be retreived over the Gateway using [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds). +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 From c08c6a9a104613b3c92bf17648142dc2daa78683 Mon Sep 17 00:00:00 2001 From: advaith Date: Wed, 28 Jun 2023 02:52:29 -0700 Subject: [PATCH 03/20] fix guild_ids desc --- docs/topics/Gateway_Events.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/topics/Gateway_Events.md b/docs/topics/Gateway_Events.md index 27a236fd71..e988489499 100644 --- a/docs/topics/Gateway_Events.md +++ b/docs/topics/Gateway_Events.md @@ -206,9 +206,9 @@ Used to request soundboard sounds for a list of guilds. The server will send [So ###### Request Soundboard Sounds Structure -| Field | Type | Description | Required | -| ---------- | ------------------- | --------------------------------------------- | -------- | -| guild_ids | array of snowflakes | ID of the guilds to get soundboard sounds for | true | +| Field | Type | Description | Required | +| ---------- | ------------------- | ---------------------------------------------- | -------- | +| guild_ids | array of snowflakes | IDs of the guilds to get soundboard sounds for | true | ###### Example Request Soundboard Sounds From 8aef30a8fe0d7cc8836019d998956d5f373f7db4 Mon Sep 17 00:00:00 2001 From: advaith Date: Wed, 15 May 2024 08:58:05 -0700 Subject: [PATCH 04/20] update table formatting --- docs/resources/Soundboard.md | 8 ++++---- docs/topics/Gateway_Events.md | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index e796765446..e1e32bdb0a 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -11,7 +11,7 @@ Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Re ###### Soundboard Sound Structure | Field | Type | Description | -| ------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------- | +|---------------|-------------------------------------------------|----------------------------------------------------------------------------------------------| | name | string | the name of this sound | | sound_id | snowflake | the id of this sound | | id? | snowflake | the id of this sound | @@ -35,7 +35,7 @@ https://cdn.discordapp.com/ ###### CDN Endpoints | Type | Path | -| ------------------------ | --------------------------------------------- | +|--------------------------|-----------------------------------------------| | Soundboard Sound | soundboard-sounds/sound_id | | Soundboard Default Sound | soundboard-default-sounds/sound_override_path | @@ -56,7 +56,7 @@ Create a new soundboard sound for the guild. Requires the `MANAGE_GUILD_EXPRESSI ###### 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 | @@ -76,7 +76,7 @@ Modify the given soundboard sound. Requires the `MANAGE_GUILD_EXPRESSIONS` permi ###### 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 | diff --git a/docs/topics/Gateway_Events.md b/docs/topics/Gateway_Events.md index 158668533c..4b434789bd 100644 --- a/docs/topics/Gateway_Events.md +++ b/docs/topics/Gateway_Events.md @@ -206,9 +206,9 @@ Used to request soundboard sounds for a list of guilds. The server will send [So ###### Request Soundboard Sounds Structure -| Field | Type | Description | Required | -| ---------- | ------------------- | ---------------------------------------------- | -------- | -| guild_ids | array of snowflakes | IDs of the guilds to get soundboard sounds for | true | +| Field | Type | Description | Required | +|-----------|---------------------|------------------------------------------------|----------| +| guild_ids | array of snowflakes | IDs of the guilds to get soundboard sounds for | true | ###### Example Request Soundboard Sounds @@ -843,7 +843,7 @@ Sent when a guild soundboard sound is deleted. ###### Guild Soundboard Sound Delete Event Fields | Field | Type | Description | -| -------- | --------- | -------------------------------- | +|----------|-----------|----------------------------------| | sound_id | snowflake | ID of the sound that was deleted | | guild_id | snowflake | ID of the guild the sound was in | @@ -854,7 +854,7 @@ Includes a guild's list of soundboard sounds. Sent in response to [Request Sound ###### Soundboard Sounds Event Fields | Field | Type | Description | -| ----------------- | --------------------------------------------------------------------------------------- | ----------------------------- | +|-------------------|-----------------------------------------------------------------------------------------|-------------------------------| | soundboard_sounds | array of [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) objects | The guild's soundboard sounds | | guild_id | snowflake | ID of the guild | From ea41d44deb8c1ad88a489e656d830eb47b9d3388 Mon Sep 17 00:00:00 2001 From: advaith Date: Wed, 15 May 2024 23:17:43 -0700 Subject: [PATCH 05/20] updates --- docs/resources/Soundboard.md | 36 ++++++++++++++--------------------- docs/topics/Gateway_Events.md | 5 +++++ 2 files changed, 19 insertions(+), 22 deletions(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index e1e32bdb0a..a904abe120 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -10,35 +10,27 @@ Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Re ###### Soundboard Sound Structure -| Field | Type | Description | -|---------------|-------------------------------------------------|----------------------------------------------------------------------------------------------| -| name | string | the name of this sound | -| sound_id | snowflake | the id of this 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 | -| override_path | ?string | the filename of this sound (for default sounds) | -| 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 | +| Field | Type | Description | +|------------|-------------------------------------------------|----------------------------------------------------------------------------------------------| +| name | string | the name of this sound | +| sound_id | snowflake | the id of this 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 -###### Base URL +A soundboard sound can be retrieved in MP3 format at the URL: ``` -https://cdn.discordapp.com/ +https://cdn.discordapp.com/soundboard-sounds/{sound_id} ``` -###### CDN Endpoints - -| Type | Path | -|--------------------------|-----------------------------------------------| -| Soundboard Sound | soundboard-sounds/sound_id | -| Soundboard Default Sound | soundboard-default-sounds/sound_override_path | - ## 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. diff --git a/docs/topics/Gateway_Events.md b/docs/topics/Gateway_Events.md index 4b434789bd..0fd9dd903d 100644 --- a/docs/topics/Gateway_Events.md +++ b/docs/topics/Gateway_Events.md @@ -338,6 +338,10 @@ Receive events are Gateway events encapsulated in an [event payload](#DOCS_TOPIC | [Guild Scheduled Event Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-delete) | Guild scheduled event was deleted | | [Guild Scheduled Event User Add](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-user-add) | User subscribed to a guild scheduled event | | [Guild Scheduled Event User Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-user-remove) | User unsubscribed from a guild scheduled event | +| [Guild Soundboard Sound Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-create) | Guild soundboard sound was created | +| [Guild Soundboard Sound Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-update) | Guild soundboard sound was updated | +| [Guild Soundboard Sound Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-delete) | Guild soundboard sound was deleted | +| [Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/soundboard-sounds) | Response to [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds) | | [Integration Create](#DOCS_TOPICS_GATEWAY_EVENTS/integration-create) | Guild integration was created | | [Integration Update](#DOCS_TOPICS_GATEWAY_EVENTS/integration-update) | Guild integration was updated | | [Integration Delete](#DOCS_TOPICS_GATEWAY_EVENTS/integration-delete) | Guild integration was deleted | @@ -616,6 +620,7 @@ The inner payload can be: | presences | array of partial [presence update](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update) objects | Presences of the members in the guild, will only include non-offline members if the size is greater than `large threshold` | | stage_instances | array of [stage instance](#DOCS_RESOURCES_STAGE_INSTANCE/stage-instance-object) objects | Stage instances in the guild | | guild_scheduled_events | array of [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) objects | Scheduled events in the guild | +| soundboard_sounds | array of [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) objects | Soundboard sounds in the guild | > warn > If your bot does not have the `GUILD_PRESENCES` [Gateway Intent](#DOCS_TOPICS_GATEWAY/gateway-intents), or if the guild has over 75k members, members and presences returned in this event will only contain your bot and users in voice channels. From e78e7535e9bd3b2d302f4da8e07ea29013182c5c Mon Sep 17 00:00:00 2001 From: advaith Date: Thu, 16 May 2024 00:12:27 -0700 Subject: [PATCH 06/20] add audit log events --- docs/resources/Audit_Log.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/resources/Audit_Log.md b/docs/resources/Audit_Log.md index 9521448bc7..452fcd126f 100644 --- a/docs/resources/Audit_Log.md +++ b/docs/resources/Audit_Log.md @@ -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) | From 00d36a96b8fb84abd6b72499dea977a7b30d57b4 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Thu, 25 Jul 2024 18:12:04 -0700 Subject: [PATCH 07/20] remove deprecated id field --- docs/resources/Soundboard.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index a904abe120..df573b2a1d 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -14,7 +14,6 @@ Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Re |------------|-------------------------------------------------|----------------------------------------------------------------------------------------------| | name | string | the name of this sound | | sound_id | snowflake | the id of this 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 | From f218e93a49dac7e9b628d40ab1b10291ac0435e8 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Fri, 26 Jul 2024 15:15:07 -0700 Subject: [PATCH 08/20] remove required column --- docs/topics/Gateway_Events.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/topics/Gateway_Events.md b/docs/topics/Gateway_Events.md index 0fd9dd903d..ae88eb7725 100644 --- a/docs/topics/Gateway_Events.md +++ b/docs/topics/Gateway_Events.md @@ -206,9 +206,9 @@ Used to request soundboard sounds for a list of guilds. The server will send [So ###### Request Soundboard Sounds Structure -| Field | Type | Description | Required | -|-----------|---------------------|------------------------------------------------|----------| -| guild_ids | array of snowflakes | IDs of the guilds to get soundboard sounds for | true | +| Field | Type | Description | +|-----------|---------------------|------------------------------------------------| +| guild_ids | array of snowflakes | IDs of the guilds to get soundboard sounds for | ###### Example Request Soundboard Sounds From ec8656239280b89c512e92921b1e43717fcaa6c6 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Mon, 29 Jul 2024 14:09:17 -0700 Subject: [PATCH 09/20] remove user_id and make available required --- docs/resources/Soundboard.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index df573b2a1d..f9012dd873 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -10,17 +10,16 @@ Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Re ###### 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 | +| 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 | ### Sound Files From 8e1809595d0c0ef25202ab1113944c762bda5dbd Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Mon, 29 Jul 2024 14:10:34 -0700 Subject: [PATCH 10/20] - --- docs/resources/Soundboard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index f9012dd873..fa725b180c 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -11,7 +11,7 @@ Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Re ###### 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 | From 8b05cc635a003706658b997450ecfef4e4cf9e23 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Wed, 14 Aug 2024 17:04:38 -0700 Subject: [PATCH 11/20] updates --- docs/resources/Soundboard.md | 55 ++++++++++++++++++++++++++--------- docs/topics/Gateway.md | 6 +++- docs/topics/Gateway_Events.md | 5 ++++ 3 files changed, 51 insertions(+), 15 deletions(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index fa725b180c..f57fd6a097 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -1,6 +1,6 @@ # 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). +Users can play soundboard sounds in voice channels, triggering a Voice Channel Effect Send Gateway event for users connected to the voice channel. 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. @@ -23,19 +23,46 @@ Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Re ### Sound Files -A soundboard sound can be retrieved in MP3 format at the URL: +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 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's [voice state](#DOCS_RESOURCES_VOICE/voice-state-object) to not have `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 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. +## 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. + +###### 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 `MANAGE_GUILD_EXPRESSIONS` permission, or if the bot created the emoji and has the the `CREATE_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 `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. +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. @@ -45,20 +72,20 @@ Create a new soundboard sound for the guild. Requires the `MANAGE_GUILD_EXPRESSI ###### 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 | +| 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. 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. +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, but the volume and emoji will be cleared if they are not included. +> All parameters to this endpoint are optional. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -68,13 +95,13 @@ Modify the given soundboard sound. Requires the `MANAGE_GUILD_EXPRESSIONS` permi | 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 | +| 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. 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. +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. diff --git a/docs/topics/Gateway.md b/docs/topics/Gateway.md index fa61d5fe0e..99ba5819c8 100644 --- a/docs/topics/Gateway.md +++ b/docs/topics/Gateway.md @@ -319,9 +319,13 @@ GUILD_MODERATION (1 << 2) - GUILD_BAN_ADD - GUILD_BAN_REMOVE -GUILD_EMOJIS_AND_STICKERS (1 << 3) +GUILD_EXPRESSIONS (1 << 3) - GUILD_EMOJIS_UPDATE - GUILD_STICKERS_UPDATE + - GUILD_SOUNDBOARD_SOUND_CREATE + - GUILD_SOUNDBOARD_SOUND_UPDATE + - GUILD_SOUNDBOARD_SOUND_DELETE + - GUILD_SOUNDBOARD_SOUNDS_UPDATE GUILD_INTEGRATIONS (1 << 4) - GUILD_INTEGRATIONS_UPDATE diff --git a/docs/topics/Gateway_Events.md b/docs/topics/Gateway_Events.md index ae88eb7725..67d17b6ead 100644 --- a/docs/topics/Gateway_Events.md +++ b/docs/topics/Gateway_Events.md @@ -341,6 +341,7 @@ Receive events are Gateway events encapsulated in an [event payload](#DOCS_TOPIC | [Guild Soundboard Sound Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-create) | Guild soundboard sound was created | | [Guild Soundboard Sound Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-update) | Guild soundboard sound was updated | | [Guild Soundboard Sound Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-delete) | Guild soundboard sound was deleted | +| [Guild Soundboard Sounds Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sounds-update) | Guild soundboard sounds were updated | | [Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/soundboard-sounds) | Response to [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds) | | [Integration Create](#DOCS_TOPICS_GATEWAY_EVENTS/integration-create) | Guild integration was created | | [Integration Update](#DOCS_TOPICS_GATEWAY_EVENTS/integration-update) | Guild integration was updated | @@ -852,6 +853,10 @@ Sent when a guild soundboard sound is deleted. | sound_id | snowflake | ID of the sound that was deleted | | guild_id | snowflake | ID of the guild the sound was in | +#### Guild Soundboard Sounds Update + +Sent when multiple guild soundboard sounds are updated. The inner payload is an array of [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) objects. + #### Soundboard Sounds Includes a guild's list of soundboard sounds. Sent in response to [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds). From 4c2c18236103e9bf85e9a373f0b40e9bd338a453 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Wed, 14 Aug 2024 17:09:57 -0700 Subject: [PATCH 12/20] changelog --- docs/Change_Log.md | 6 ++++++ docs/resources/Soundboard.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/Change_Log.md b/docs/Change_Log.md index 28724d3672..fdb6ff5d36 100644 --- a/docs/Change_Log.md +++ b/docs/Change_Log.md @@ -1,5 +1,11 @@ # Change Log +## Soundboard API + +#### August 14, 2024 + +[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-sounds) them, [send](#DOCS_RESOURCES_SOUNDBOARD/send-soundboard-sound) them in voice channels, and listen to other users playing them! + ## Voice Encryption Modes #### August 13, 2024 diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index f57fd6a097..4a7196f067 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -42,7 +42,7 @@ Requires the `SPEAK` and `USE_SOUNDBOARD` permissions, and also the `USE_EXTERNA | 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 Soundboard Default Sounds % GET /soundboard-default-sounds +## 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. From 292f14fb361c7ddca302a33dbd86bc33515589f8 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Wed, 14 Aug 2024 17:35:56 -0700 Subject: [PATCH 13/20] fix links --- docs/Change_Log.md | 2 +- docs/resources/Soundboard.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Change_Log.md b/docs/Change_Log.md index fdb6ff5d36..0a58d8bb61 100644 --- a/docs/Change_Log.md +++ b/docs/Change_Log.md @@ -4,7 +4,7 @@ #### August 14, 2024 -[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-sounds) them, [send](#DOCS_RESOURCES_SOUNDBOARD/send-soundboard-sound) them in voice channels, and listen to other users playing them! +[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! ## Voice Encryption Modes diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index 4a7196f067..61bc3e93fb 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -2,7 +2,7 @@ Users can play soundboard sounds in voice channels, triggering a Voice Channel Effect Send Gateway event for users connected to the voice channel. -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-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). From ea5fd677e0c75770651725700cde61b2062b61c6 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Fri, 16 Aug 2024 20:01:02 -0700 Subject: [PATCH 14/20] fix get permissions --- docs/resources/Soundboard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index 61bc3e93fb..fa2b5e1ea2 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -58,7 +58,7 @@ Returns a list of the guild's soundboard sounds. Includes `user` fields if the b ## 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 `MANAGE_GUILD_EXPRESSIONS` permission, or if the bot created the emoji and has the the `CREATE_GUILD_EXPRESSIONS` permission. +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 From 7359836bff0e73f5cd18c9f10474db9d20dcfb07 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Mon, 26 Aug 2024 15:48:56 -0700 Subject: [PATCH 15/20] link to vc effect event --- docs/resources/Soundboard.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index fa2b5e1ea2..cfa43e54f3 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -1,6 +1,6 @@ # 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. +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. @@ -31,7 +31,7 @@ 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 Gateway event. +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's [voice state](#DOCS_RESOURCES_VOICE/voice-state-object) to not have `deaf`, `self_deaf`, `mute`, or `suppress` enabled. From 5a13333fb29e2324058bec21306125b9a69dfcbd Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Fri, 30 Aug 2024 18:34:23 -0700 Subject: [PATCH 16/20] constants --- docs/resources/Guild.md | 1 + docs/topics/Opcodes_and_Status_Codes.md | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/docs/resources/Guild.md b/docs/resources/Guild.md index 499651f435..44316cb0cc 100644 --- a/docs/resources/Guild.md +++ b/docs/resources/Guild.md @@ -142,6 +142,7 @@ Guilds in Discord represent an isolated collection of users and channels, and ar | INVITES_DISABLED | guild has paused invites, preventing new users from joining | | INVITE_SPLASH | guild has access to set an invite splash background | | MEMBER_VERIFICATION_GATE_ENABLED | guild has enabled [Membership Screening](#DOCS_RESOURCES_GUILD/membership-screening-object) | +| MORE_SOUNDBOARD | guild has increased custom soundboard sound slots | | MORE_STICKERS | guild has increased custom sticker slots | | NEWS | guild has access to create announcement channels | | PARTNERED | guild is partnered | diff --git a/docs/topics/Opcodes_and_Status_Codes.md b/docs/topics/Opcodes_and_Status_Codes.md index 490120b5d8..5e4a2fa2c5 100644 --- a/docs/topics/Opcodes_and_Status_Codes.md +++ b/docs/topics/Opcodes_and_Status_Codes.md @@ -154,6 +154,7 @@ Along with the HTTP error code, our API can also return more detailed error code | 10070 | Unknown Guild Scheduled Event | | 10071 | Unknown Guild Scheduled Event User | | 10087 | Unknown Tag | +| 10097 | Unknown sound | | 20001 | Bots cannot use this endpoint | | 20002 | Only bots can use this endpoint | | 20009 | Explicit content cannot be sent to the desired recipient(s) | @@ -191,6 +192,7 @@ Along with the HTTP error code, our API can also return more detailed error code | 30039 | Maximum number of stickers reached | | 30040 | Maximum number of prune requests has been reached. Try again later | | 30042 | Maximum number of guild widget settings updates has been reached. Try again later | +| 30045 | Maximum number of soundboard sounds reached | | 30046 | Maximum number of edits to messages older than 1 hour reached. Try again later | | 30047 | Maximum number of pinned threads in a forum channel has been reached | | 30048 | Maximum number of tags in a forum channel has been reached | @@ -272,6 +274,7 @@ Along with the HTTP error code, our API can also return more detailed error code | 50101 | This server needs more boosts to perform this action | | 50109 | The request body contains invalid JSON. | | 50110 | The provided file is invalid. | +| 50123 | The provided file type is invalid. | | 50124 | The provided file duration exceeds maximum of 5.2 seconds. | | 50131 | Owner cannot be pending member | | 50132 | Ownership cannot be transferred to a bot user | @@ -279,6 +282,7 @@ Along with the HTTP error code, our API can also return more detailed error code | 50144 | Cannot mix subscription and non subscription roles for an emoji | | 50145 | Cannot convert between premium emoji and normal emoji | | 50146 | Uploaded file not found. | +| 50151 | The specified emoji is invalid | | 50159 | Voice messages do not support additional content. | | 50160 | Voice messages must have a single audio attachment. | | 50161 | Voice messages must have supporting metadata. | @@ -286,6 +290,7 @@ Along with the HTTP error code, our API can also return more detailed error code | 50163 | Cannot delete guild subscription integration | | 50173 | You cannot send voice messages in this channel. | | 50178 | The user account must first be verified | +| 50192 | The provided file does not have a valid duration. | | 50600 | You do not have permission to send this sticker. | | 60003 | Two factor is required for this operation | | 80004 | No users with DiscordTag exist | From 3c618759b8dfa081830633f4ee585d705b0acedf Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Fri, 30 Aug 2024 18:38:43 -0700 Subject: [PATCH 17/20] re-add changelog --- docs/change_log/2024-08-30-soundboard-api.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 docs/change_log/2024-08-30-soundboard-api.md diff --git a/docs/change_log/2024-08-30-soundboard-api.md b/docs/change_log/2024-08-30-soundboard-api.md new file mode 100644 index 0000000000..985ca71217 --- /dev/null +++ b/docs/change_log/2024-08-30-soundboard-api.md @@ -0,0 +1,6 @@ +--- +title: "Soundboard API" +date: "2024-08-30" +--- + +[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-sounds) them, [send](#DOCS_RESOURCES_SOUNDBOARD/send-soundboard-sound) them in voice channels, and listen to other users playing them! From 451010c572ee03a76dd4879de33efdc05c8b12d5 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Fri, 30 Aug 2024 18:39:49 -0700 Subject: [PATCH 18/20] fix link again --- docs/change_log/2024-08-30-soundboard-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/change_log/2024-08-30-soundboard-api.md b/docs/change_log/2024-08-30-soundboard-api.md index 985ca71217..8e040971d6 100644 --- a/docs/change_log/2024-08-30-soundboard-api.md +++ b/docs/change_log/2024-08-30-soundboard-api.md @@ -3,4 +3,4 @@ title: "Soundboard API" date: "2024-08-30" --- -[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-sounds) them, [send](#DOCS_RESOURCES_SOUNDBOARD/send-soundboard-sound) them in voice channels, and listen to other users playing them! +[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! From f4c5ff3418f49354bf033f3e34b5441aee8e925d Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Thu, 19 Sep 2024 22:36:47 -0700 Subject: [PATCH 19/20] fixes and examples --- ...rd-api.md => 2024-00-20-soundboard-api.md} | 2 +- docs/resources/Soundboard.md | 36 +++++++++++++++++-- 2 files changed, 35 insertions(+), 3 deletions(-) rename docs/change_log/{2024-08-30-soundboard-api.md => 2024-00-20-soundboard-api.md} (95%) diff --git a/docs/change_log/2024-08-30-soundboard-api.md b/docs/change_log/2024-00-20-soundboard-api.md similarity index 95% rename from docs/change_log/2024-08-30-soundboard-api.md rename to docs/change_log/2024-00-20-soundboard-api.md index 8e040971d6..d71436b845 100644 --- a/docs/change_log/2024-08-30-soundboard-api.md +++ b/docs/change_log/2024-00-20-soundboard-api.md @@ -1,6 +1,6 @@ --- title: "Soundboard API" -date: "2024-08-30" +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! diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index cfa43e54f3..e99df3f4ea 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -1,3 +1,7 @@ +--- +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. @@ -21,6 +25,34 @@ Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Re | 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 A soundboard sound can be retrieved in MP3 or Ogg format at the URL: @@ -31,9 +63,9 @@ 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. +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's [voice state](#DOCS_RESOURCES_VOICE/voice-state-object) to not have `deaf`, `self_deaf`, `mute`, or `suppress` enabled. +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 From 8069f6afb2a28ed5134d8bed947ae96f306061c2 Mon Sep 17 00:00:00 2001 From: Advaith Jagathesan Date: Thu, 19 Sep 2024 22:42:06 -0700 Subject: [PATCH 20/20] delete extra line --- docs/resources/Soundboard.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index e99df3f4ea..eb6b34236e 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -40,7 +40,6 @@ Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Re ###### Example Guild Soundboard Sound - ```json { "name": "Yay",