Voice Gateway Versioning
To ensure that you have the most up-to-date information, please use version 8. Otherwise, we cannot guarantee that the Opcodes documented here will reflect what you receive over the socket. Previously if the version query stringv was omitted the voice gateway would default to version 1. That behavior is being deprecated, in the future you must present a voice gateway version or your voice connection will be rejected.
Versions below 4 as well as the default version behavior will be discontinued as of November 18th, 2024. Connections without a version or with a version less than version 4 will be rejected as of this date.
Gateway Versions
| Version | Status | WebSocket URL Append | Change | 
|---|---|---|---|
| 8 | recommended | ?v=8 | Added server message buffering, missed messages re-delivered on resume | 
| 7 | available | ?v=7 | Added channel options opcode | 
| 6 | available | ?v=6 | Added code version opcode | 
| 5 | available | ?v=5 | Added video sink wants opcode | 
| 4 | available | ?v=4 | Changed speaking status to bitmask from boolean | 
| 3 | deprecated | ?v=3 | Added video | 
| 2 | deprecated | ?v=2 | Changed heartbeat reply from server to heartbeak ACK opcode | 
| 1 | deprecated | ?v=1 | Initial version | 
Connecting to Voice
Retrieving Voice Server Information
The first step in connecting to a voice server (and in turn, a guild’s voice channel) is formulating a request that can be sent to the Gateway, which will return information about the voice server we will connect to. Because Discord’s voice platform is widely distributed, users should never cache or save the results of this call. To inform the gateway of our intent to establish voice connectivity, we first send an Opcode 4 Gateway Voice State Update:Gateway Voice State Update Example
session_id, and the second will provide voice server information we can use to establish a new voice connection:
Example Voice Server Update Payload
endpoint as the previous VOICE_SERVER_UPDATE. The token will be changed and you cannot re-use the previous session during a channel change, even if the endpoint remains the same.
Bot users respect the voice channel’s user limit, if set. When the voice channel is full, you will not receive the Voice State Update or Voice Server Update events in response to your own Voice State Update. Having 
MANAGE_CHANNELS permission bypasses this limit and allows you to join regardless of the channel being full or not.Establishing a Voice Websocket Connection
Once we retrieve a session_id, token, and endpoint information, we can connect and handshake with the voice server over another secure WebSocket. Unlike the gateway endpoint we receive in an HTTP Get Gateway request, the endpoint received from our Voice Server Update payload does not contain a URL protocol, so some libraries may require manually prepending it with “wss://” before connecting. Once connected to the voice WebSocket endpoint, we can send an Opcode 0 Identify payload with our server_id, user_id, session_id, and token:Example Voice Identify Payload
SSRC, UDP IP/port, and supported encryption modes the voice server expects:
Example Voice Ready Payload
heartbeat_interval here is an erroneous field and should be ignored. The correct heartbeat_interval value comes from the Hello payload.Heartbeating
In order to maintain your WebSocket connection, you need to continuously send heartbeats at the interval determined in Opcode 8 Hello:Example Hello Payload
Example Heartbeat Payload since V8
seq_ack which contains the sequence number of last numbered message received from the gateway. See Buffered Resume for more information.
Example Heartbeat Payload below V8
Example Heartbeat ACK Payload since V8
Example Heartbeat ACK Payload below V8
Establishing a Voice UDP Connection
Once we receive the properties of a UDP voice server from our Opcode 2 Ready payload, we can proceed to the final step of voice connections, which entails establishing and handshaking a UDP connection for voice data.Example Ready Payload
Example Select Protocol Payload
End-to-End Encryption (DAVE Protocol)
Since September 2024, Discord is migrating voice and video in DMs, Group DMs, voice channels, and Go Live streams to use end-to-end encryption (E2EE).To support our long-term privacy goals, we will only support E2EE calls starting on March 1st, 2026 for all audio
and video conversations in direct messages (DMs), group messages (GDMs), voice channels, and Go Live streams on
Discord.
We highly recommend you implement DAVE support as soon as possible to ensure a smooth transition.
We highly recommend you implement DAVE support as soon as possible to ensure a smooth transition.
Binary Websocket Messages
To reduce overhead, some of the new DAVE protocol opcodes are sent as binary instead of JSON text. See the binary column in the Voice Opcodes Table to identify these opcodes. Binary websocket messages have the following format:| Field | Description | Size | 
|---|---|---|
| Sequence Number | OPTIONAL (server -> client only) big-endian uint16 sequence number | 2 bytes | 
| Opcode | Unsigned integer opcode value | 1 bytes | 
| Payload | Binary message payload (format defined by opcode) | Variable bytes | 
Indicating DAVE Protocol Support
Include the highest DAVE protocol version you support in Opcode 0 Identify asmax_dave_protocol_version. Sending version 0, or omitting the max_dave_protocol_version field, indicates no DAVE protocol support.
The voice gateway specifies the initial protocol version in Opcode 4 Session Description under dave_protocol_version. This may be any non-discontinued protocol version equal to or less than your supported protocol version.
Clients must retain backwards-compatibility of any non-discontinued DAVE protocol versions. The voice gateway selects the lowest shared protocol version for the call.
Protocol Transitions
The voice gateway negotiates protocol version and MLS group transitions, to ensure the continuity of media being sent for the call. This can occur when the call is upgrading/downgrading to/from E2EE (in the initial transition phase), changing protocol versions, or when the MLS group is changing. Some opcodes include a transition ID. After preparing local state necessary to perform the transition, send Opcode 23 DAVE Protocol Transition Ready to indicate to the voice gateway that you are ready to execute the transition. When all participants are ready or when a timeout has been reached, the voice gateway dispatches Opcode 22 DAVE Protocol Execute Transition to confirm execution of the transition. The transition execution is what indicates to media senders that they can begin sending media with the new protocol context (e.g. without E2EE after a downgrade, with a new protocol version after a protocol version change, or using a new key ratchet after a group participant change).Downgrade
Downgrades to protocol version 0 are announced via Opcode 21 DAVE Protocol Prepare Transition. This can occur during the transition phase when a client that does not support the protocol joins the call. When this transition is executed, senders should stop sending media using the protocol format.Protocol Version Change & Upgrade
Protocol version transitions (including upgrades from protocol version 0) are announced via Opcode 24 DAVE Protocol Prepare Epoch. In addition to thetransition_id, this opcode includes the epoch_id for the upcoming MLS epoch.
Receiving Opcode 24 DAVE Protocol Prepare Epoch with epoch_id = 1 indicates that a new MLS group is being created. Participants must:
- prepare a local MLS group with the parameters appropriate for the DAVE protocol version
- generate and send Opcode 26 DAVE MLS Key Package to deliver a new MLS key package to the voice gateway
epoch_id is greater than 1, the protocol version of the existing MLS group is changing.
When the transition is executed, senders must start sending media using the new protocol context (e.g. formatted for the new protocol version or using a new key ratchet).
MLS Group Changes
When the participants of the MLS group must change, existing participants receive an Opcode 29 DAVE MLS Announce Commit Transition whereas new members being added to the group receive Opcode 30 DAVE MLS Welcome. Both opcodes include the transition ID and binary MLS Commit or MLS Welcome message. To prepare for the protocol transition, existing group members must apply the commit to progress their local MLS group to the correct next state. Opcode 23 DAVE Protocol Transition Ready is sent when the MLS commit has been processed. Welcomed members send Opcode 23 DAVE Protocol Transition Ready after succesfully joining the group received in the MLS Welcome message.External Sender
The voice gateway must be an external sender of the MLS group, so that it can send external MLS proposals to add and remove call participants when appropriate (i.e. proposing the addition of new members when they connect and the removal of previous members when they disconnect). DAVE protocol participants only process proposals which arrive from the external sender, and not from any other group members. The external sender only sends Add or Remove proposals. The voice gateway uses Opcode 25 DAVE MLS External Sender Package to provide the external sender public key and credential to MLS group participants. This message may be sent immediately on voice gateway connection or at a later time when the call is upgrading to use the DAVE protocol. Group creators must include the external sender they receive from the voice gateway in their MLS group extensions when creating the group. Welcomed group members ensure that the expected external sender extension is present in the group they are about to join.Joining the MLS Group
Except for the initial creation of the first group for the call, joining the MLS group always occurs after receiving Opcode 30 DAVE MLS Welcome.Key Packages
To be proposed to be added to the MLS group, pending members must send an MLS key package via Opcode 26 DAVE MLS Key Package. Key packages are only used one time, and a new key package must be generated each time pending member is waiting to be added or re-added to the group.Identity Public Key
MLS participants use an asymmetric keypair for MLS message signatures and authentication. The public key of this keypair is included in the key package and MLS tree. It is known to other participants in the call and is leveraged for out-of-band identity verification. You can choose to generate a new ephemeral keypair for every protocol call or use the same persistent keypair at all times.Initial Group
When there is not yet an MLS group (e.g. a transport-only encrypted call is upgrading or two members have just joined a new call) all pending group members create a local group using the MLS parameters defined by the DAVE protocol version and including the voice gateway external sender received via Opcode 25 DAVE MLS External Sender Package. Every pending member of the group has the chance to produce the initial commit that creates the MLS group withepoch = 1.
Pending group members receive add proposals for every other pending group member from the voice gateway. If an additional pending member joins while there is not yet an MLS group, they receive all in-flight proposal messages.
Proposal and commit handling follows the same process whether or not there is an established group. See Proposals and Commits
Welcome
Pending group members receive a welcome message from another group member which adds them to the MLS group. This is dispatched from the voice gateway via Opcode 30 DAVE MLS Welcome.Invalid Group
If the group received in an Opcode 30 DAVE MLS Welcome or Opcode 29 DAVE MLS Announce Commit Transition is unprocessable, the member receiving the unprocessable message sends Opcode 31 DAVE MLS Invalid Commit Welcome to the voice gateway. Additionally, the local group state is reset and a new key package is generated and sent to the voice gateway via Opcode 26 DAVE MLS Key Package. This causes the voice gateway to propose the removal and re-addition of the requesting member.Proposals and Commits
The voice gateway dispatches proposals which must be appended or revoked via Opcode 27 DAVE MLS Proposals. All members of the established or pending MLS group must append or revoke the proposals they receive, and then produce an MLS commit message and optionally an MLS welcome message (when committing add proposals which add new members) which they send to the voice gateway via Opcode 28 DAVE MLS Commit Welcome. In each epoch, the voice gateway dispatches the “winning” commit via Opcode 29 DAVE MLS Announce Commit Transition and optionally the associated welcome messages via Opcode 30 DAVE MLS Welcome. The voice gateway broadcasts the first valid commit and welcome(s) it sees in the given epoch, and drops any commits later received for the out-of-date epoch. All dispatched unrevoked proposals in the epoch must be included in the commit for it to be valid. All members added in the epoch must be welcomed for the welcome to be valid.Audio Frame E2EE
While transport-encryption operates at the packet level, E2EE enabled by the DAVE protocol operates at the frame level. When any DAVE protocol is enabled for a call, the full contents of OPUS frames sent and received by call participants are end-to-end encrypted.ULEB128 Encoding
Some fields in the protocol frame payload use ULEB128 encoding. This is a variable-length code compression to represent arbitrarily large unsigned integers in a small number of bytes.Payload Format
| Field | Description | Size | 
|---|---|---|
| E2EE OPUS Frame | Ciphertext for E2EE OPUS frame | Variable bytes | 
| AES-GCM Auth. Tag | Truncated AES128-GCM AEAD Authentication Tag | 8 bytes | 
| ULEB128 Nonce | ULEB128 synchronization nonce | Variable bytes | 
| ULEB128 Unencrypted Ranges | ULEB128 offset/length pairs of E2EE frame unencrypted data | Variable bytes | 
| Supplemental Data Size | Unsigned integer bytes size of supplemental data | 1 byte | 
| Magic Marker | 0xFAFA marker to assist with protocol frame identification | 2 bytes | 
- 8-byte authentication tag
- Variable length ULEB128 nonce
- Variable length ULEB128 unencrypted ranges
- 1 byte supplemental data size
- 2 byte magic marker
Frame Encryption
Media frames are encrypted for E2EE using AES128-GCM.Sender Key Derivation
Each media sender has a ratcheted per-sender key. There is a new per-sender ratchet created in each MLS group epoch. The initial secret for each sender’s ratchet is an exported 16-byte secret from the MLS group. Keys are retrieved from the ratchet via a generation counter derived from the most-significant byte of the 4-byte nonce. For very long lived epochs, the nonce wrap-around must be handled so the generation does not also wrap back around to 0. See the Sender Key Derivation section of the Protocol Whitepaper for the detailed process.Nonce
The nonce passed to the AES128-GCM encryption and decryption functions is a full 12-byte nonce, but the protocol only uses at most 4-bytes. The 12-byte nonce can be expanded from a 4-byte truncated nonce by setting the 8 most significant bytes of the nonce to zero, with the 4 least significant bytes carrying the value of the truncated nonce. The generation used for the sender’s key ratchet is retrieved from the most-significant byte of the 4-byte nonce (i.e., the 4th least significant byte of the full 12-byte nonce).Authentication Tag
The authentication tag resulting from the AES128-GCM encryption is truncated to 8 bytes. Some implementations may provide the desired tag length as a parameter whereas some may always return the full 12-byte tag from which the 4 least significant bytes should be removed.AEAD Additional Data
OPUS frames are fully encrypted and no additional data is passed to the AEAD.Transport Encryption and Sending Voice
Transport encryption between the client and the selective forwarding unit (SFU) is still used even in E2EE calls. Voice data sent to discord should be encoded with Opus, using two channels (stereo) and a sample rate of 48kHz. Voice Data is sent using a RTP Header, followed by encrypted Opus audio data. Voice encryption uses the key passed in Opcode 4 Session Description and the nonce formed with the 12 byte header appended with 12 null bytes to achieve the 24 required by xsalsa20_poly1305. Discord encrypts with the libsodium encryption library.Transport Encryption Modes
| Mode | Key | Nonce | Status | 
|---|---|---|---|
| AEAD AES256-GCM (RTP Size) | aead_aes256_gcm_rtpsize | 32-bit incremental integer value, appended to payload | Available (Preferred) | 
| AEAD XChaCha20 Poly1305 (RTP Size) | aead_xchacha20_poly1305_rtpsize | 32-bit incremental integer value, appended to payload | Available (Required) | 
| XSalsa20 Poly1305 Lite (RTP Size) | xsalsa20_poly1305_lite_rtpsize | 32-bit incremental integer value, appended to payload | Deprecated | 
| AEAD AES256-GCM | aead_aes256_gcm | 32-bit incremental integer value, appended to payload | Deprecated | 
| XSalsa20 Poly1305 | xsalsa20_poly1305 | Copy of RTP header | Deprecated | 
| XSalsa20 Poly1305 Suffix | xsalsa20_poly1305_suffix | 24 random bytes | Deprecated | 
| XSalsa20 Poly1305 Lite | xsalsa20_poly1305_lite | 32-bit incremental integer value, appended to payload | Deprecated | 
The deprecated encryption modes above will be discontinued as of November 18th, 2024. As of this date the voice gateway will not allow you to connect with one of the deprecated encryption modes.
The nonce has to be stripped from the payload before encrypting and before decrypting the audio data
aead_xchacha20_poly1305_rtpsize but may not include aead_aes256_gcm_rtpsize depending on the underlying hardware. You must support aead_xchacha20_poly1305_rtpsize. You should prefer to use aead_aes256_gcm_rtpsize when it is available.
Include your selected mode in Opcode 1 Select Protocol.
Finally, the voice server will respond with a Opcode 4 Session Description that includes the mode and secret_key, a 32 byte array used for transport encryption and sending voice data:
Example Session Description Payload
Voice Packet Structure
| Field | Type | Size | 
|---|---|---|
| Version + Flags | Single byte value of 0x80 | 1 byte | 
| Payload Type | Single byte value of 0x78 | 1 byte | 
| Sequence | Unsigned short (big endian) | 2 bytes | 
| Timestamp | Unsigned integer (big endian) | 4 bytes | 
| SSRC | Unsigned integer (big endian) | 4 bytes | 
| Encrypted audio | Binary data | n bytes | 
Speaking
Speaking updates are used to update the speaking modes used by the client. This speaking mode is set using a Opcode 5 Speaking payload. The client must send this at least once before sending audio to update the SSRC and set the initial speaking mode. The following flags can be used as a bitwise mask. For example5 would be priority and voice. The speaking mode should not be 0 to allow sending audio.
| Flag | Meaning | Value | 
|---|---|---|
| Microphone | Normal transmission of voice audio | 1 << 0 | 
| Soundshare | Transmission of context audio for video, no speaking indicator | 1 << 1 | 
| Priority | Priority speaker, lowering audio of other speakers | 1 << 2 | 
Example Speaking Payload
You must send at least one Opcode 5 Speaking payload before sending voice data, or you will be disconnected with an invalid SSRC error.
The 
delay property should be set to 0 for bots that use the voice gateway.Voice Data Interpolation
When there’s a break in the sent data, the packet transmission shouldn’t simply stop. Instead, send five frames of silence (0xF8, 0xFF, 0xFE) before stopping to avoid unintended Opus interpolation with subsequent transmissions.
Resuming Voice Connection
When your client detects that its connection has been severed, it should open a new WebSocket connection. Once the new connection has been opened, your client should send an Opcode 7 Resume payload:Example Resume Connection Payload Since V8
Example Resume Connection Payload Before V8
Example Resumed Payload
Buffered Resume
Since voice gateway version 8, the gateway can resend buffered messages that have been lost upon resume. To support this, the gateway includes a sequence number with all messages that may need to be re-sent.Example Message With Sequence Number
d key as seq_ack in both the Opcode 3 Heartbeat and Opcode 7 Resume payloads.
If no sequence numbered messages have been received, seq_ack can be omitted or included with a value of -1.
The gateway server uses a fixed bit length sequence number and handles wrapping the sequence number around. Since voice gateway messages will always arrive in order, a client only needs to retain the last sequence number they have seen.
If the session is successfully resumed the voice gateway will respond with an Opcode 9 Resumed and will re-send any messages that the client did not receive.
The resume may be unsuccessful if the voice gateway buffer for the session no longer contains a message that has been missed. In this case the session will be closed and you should then follow the Connecting flow to reconnect.
IP Discovery
Generally routers on the Internet mask or obfuscate UDP ports through a process called NAT. Most users who implement voice will want to utilize IP discovery to find their external IP and port which will then be used for receiving voice communications. To retrieve your external IP and port, send the following UDP packet to your voice port (all numeric are big endian):| Field | Description | Size | 
|---|---|---|
| Type | Values 0x1 and 0x2 indicate request and response, respectively | 2 bytes | 
| Length | Message length excluding Type and Length fields (value 70) | 2 bytes | 
| SSRC | Unsigned integer | 4 bytes | 
| Address | Null-terminated string in response | 64 bytes | 
| Port | Unsigned short | 2 bytes |