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 1 commit
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
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
90 changes: 90 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,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).
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 retreived over the Gateway using [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds).
advaith1 marked this conversation as resolved.
Show resolved Hide resolved

### Soundboard Sound Object

###### Soundboard Sound Structure

| Field | Type | Description |
| ------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
| name | string | the name of this sound |
| sound_id | snowflake | the id of this sound |
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
| sound_id | snowflake | the id of this sound |
| sound_id | snowflake | the id of this [sound](#DOCS_RESOURCES_SOUNDBOARD/sound-files) |

| id? | snowflake | the id of this sound |
advaith1 marked this conversation as resolved.
Show resolved Hide resolved
| 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) |
advaith1 marked this conversation as resolved.
Show resolved Hide resolved
| guild_id? | snowflake | the id of the guild this sound is in |
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
| guild_id? | snowflake | the id of the guild this sound is in |
| guild_id? | snowflake | the id of the guild this sound belongs to |

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


###### 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 |
advaith1 marked this conversation as resolved.
Show resolved Hide resolved

## 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.
78 changes: 65 additions & 13 deletions docs/topics/Gateway_Events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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
Expand Down
Loading