---
sidebar_label: Soundboard
---

# Soundboard Resource

Users can play soundboard sounds in voice channels, triggering a [Voice Channel Effect Send](/docs/events/gateway-events#voice-channel-effect-send) Gateway event for users connected to the voice channel.

There is a set of [default sounds](/docs/resources/soundboard#list-default-soundboard-sounds) available to all users. Soundboard sounds can also be [created in a guild](/docs/resources/soundboard#create-guild-soundboard-sound); users will be able to use the sounds in the guild, and Nitro subscribers can use them in all guilds.

Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Request Soundboard Sounds](/docs/events/gateway-events#request-soundboard-sounds).

### Soundboard Sound Object

###### Soundboard Sound Structure

| Field      | Type                                            | Description                                                               |
|------------|-------------------------------------------------|---------------------------------------------------------------------------|
| name       | string                                          | the name of this sound                                                    |
| sound_id   | snowflake                                       | the id of this sound                                                      |
| volume     | double                                          | the volume of this sound, from 0 to 1                                     |
| emoji_id   | ?snowflake                                      | the id of this sound's custom emoji                                       |
| emoji_name | ?string                                         | the unicode character of this sound's standard emoji                      |
| guild_id?  | snowflake                                       | the id of the guild this sound is in                                      |
| available  | boolean                                         | whether this sound can be used, may be false due to loss of Server Boosts |
| user?      | [user](/docs/resources/user#user-object) object | the user who created this sound                                           |

###### Example Default Soundboard Sound

```json
{
  "name": "quack",
  "sound_id": "1",
  "volume": 1.0,
  "emoji_id": null,
  "emoji_name": "🦆",
  "available": true
}
```

###### Example Guild Soundboard Sound

```json
{
  "name": "Yay",
  "sound_id": "1106714396018884649",
  "volume": 1,
  "emoji_id": "989193655938064464",
  "emoji_name": null,
  "guild_id": "613425648685547541",
  "available": true
}
```

### Sound Files

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
<Route method="POST">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/send-soundboard-sound</Route>

Send a soundboard sound to a voice channel the user is connected to. Fires a [Voice Channel Effect Send](/docs/events/gateway-events#voice-channel-effect-send) Gateway event.

Requires the `SPEAK` and `USE_SOUNDBOARD` permissions, and also the `USE_EXTERNAL_SOUNDS` permission if the sound is from a different server. Additionally, requires the user to be connected to the voice channel, having a [voice state](/docs/resources/voice#voice-state-object) without `deaf`, `self_deaf`, `mute`, or `suppress` enabled.

###### JSON Params

| Field            | Type      | Description                                                                                      |
|------------------|-----------|--------------------------------------------------------------------------------------------------|
| sound_id         | snowflake | the id of the soundboard sound to play                                                           |
| source_guild_id? | snowflake | the id of the guild the soundboard sound is from, required to play sounds from different servers |

## List Default Soundboard Sounds
<Route method="GET">/soundboard-default-sounds</Route>

Returns an array of [soundboard sound](/docs/resources/soundboard#soundboard-sound-object) objects that can be used by all users.

## List Guild Soundboard Sounds
<Route method="GET">/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/soundboard-sounds</Route>

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
<Route method="GET">/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/soundboard-sounds/[\{sound.id\}](/docs/resources/soundboard#soundboard-sound-object)</Route>

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
<Route method="POST">/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/soundboard-sounds</Route>

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/events/gateway-events#guild-soundboard-sound-create) Gateway event.

:::info
Soundboard sounds have a max file size of 512kb and a max duration of 5.2 seconds.
:::

:::info
This endpoint supports the `X-Audit-Log-Reason` header.
:::

###### JSON Params

| Field       | Type       | Description                                                                                    |
|-------------|------------|------------------------------------------------------------------------------------------------|
| name        | string     | name of the soundboard sound (2-32 characters)                                                 |
| sound       | data uri   | the mp3 or ogg sound data, base64 encoded, similar to [image data](/docs/reference#image-data) |
| volume?     | ?double    | the volume of the soundboard sound, from 0 to 1, defaults to 1                                 |
| emoji_id?   | ?snowflake | the id of the custom emoji for the soundboard sound                                            |
| emoji_name? | ?string    | the unicode character of a standard emoji for the soundboard sound                             |

## Modify Guild Soundboard Sound
<Route method="PATCH">/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/soundboard-sounds/[\{sound.id\}](/docs/resources/soundboard#soundboard-sound-object)</Route>

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/events/gateway-events#guild-soundboard-sound-update) Gateway event.

:::warn
All parameters to this endpoint are optional.
:::

:::info
This endpoint supports the `X-Audit-Log-Reason` header.
:::

###### JSON Params

| Field      | Type       | Description                                                        |
|------------|------------|--------------------------------------------------------------------|
| name       | string     | name of the soundboard sound (2-32 characters)                     |
| volume     | ?double    | the volume of the soundboard sound, from 0 to 1                    |
| emoji_id   | ?snowflake | the id of the custom emoji for the soundboard sound                |
| emoji_name | ?string    | the unicode character of a standard emoji for the soundboard sound |

## Delete Guild Soundboard Sound
<Route method="DELETE">/guilds/[\{guild.id\}](/docs/resources/guild#guild-object)/soundboard-sounds/[\{sound.id\}](/docs/resources/soundboard#soundboard-sound-object)</Route>

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/events/gateway-events#guild-soundboard-sound-delete) Gateway event.

:::info
This endpoint supports the `X-Audit-Log-Reason` header.
:::