У голосового подключения Discord несколько независимых фаз. Команда может успешно обработаться основным Gateway, но бот не получить право `Connect`; бот может войти в канал, но остановиться до Voice Ready; либо соединение установлено, а UDP-медиа не проходит. Лог «join failed» скрывает разницу. Записывайте последнее достигнутое состояние для одной попытки.
Начните с изолированного голосового канала и одного экземпляра бота. Проверьте, что выбран именно channel ID voice-канала, бот состоит в нужном guild, канал не заполнен и итоговые права учитывают server roles и channel overwrites. Для присутствия нужно `Connect`, для отправки аудио — `Speak`; право администратора не стоит выдавать как диагностический обход.
Симптомы делят путь на четыре части
| Последнее наблюдение | Вероятная граница | Проверка |
|---|---|---|
| команда принята, событий нет | permissions, limit или Gateway request | guild/channel ID, Connect, заполненность |
| есть Voice State, нет Voice Server | основной Gateway | ожидание обоих событий и intents библиотеки |
| есть token/endpoint, нет Ready | voice WebSocket | свежая сессия, URL и версия gateway |
| Ready есть, звука нет | UDP/кодек/protocol | UDP discovery, Select Protocol, Opus |
| работает, затем обрыв | heartbeat или resume | ACK, close code и политика reconnect |
Отдельно проверьте user limit. Документация Discord предупреждает: заполненный канал может не вернуть ожидаемые Voice State Update и Voice Server Update; обход лимита связан с `MOVE_MEMBERS`. Для обычного музыкального бота разумнее освободить место, а не расширять права.
Подключение начинается в основном Gateway
Клиент отправляет Gateway Voice State Update с guild ID, channel ID и флагами mute/deaf. Успешный запрос порождает два независимых события: Voice State Update даёт `session_id`, а Voice Server Update — `token` и `endpoint`. Порядок их доставки не следует угадывать: храните части под ключом guild и продолжайте только после получения обеих.
state[guild] = {
session_id: null,
token: null,
endpoint: null,
generation: joinAttemptId
}
on VOICE_STATE_UPDATE -> save session_id
on VOICE_SERVER_UPDATE -> save token + endpoint
when all present and generation is current -> open voice WebSocketПри переходе между каналами endpoint может остаться тем же, но token меняется; прежнюю сессию переиспользовать нельзя. Поэтому позднее событие старой попытки отбрасывается по generation. Token и полный Identify payload не попадают в лог — достаточно наличия полей, guild ID и обезличенного attempt ID.
Voice WebSocket — не тот же сокет, что Gateway
К endpoint подключаются отдельным защищённым WebSocket, отправляют Voice Identify с server/user/session/token и ждут Voice Ready. Discord рекомендует актуальную voice gateway version 8. После Hello нужно посылать heartbeat с заданным интервалом и отслеживать ACK; отсутствие ACK означает не «нет аудио», а нездоровое управляющее соединение.
- Не кэшировать endpoint и token между подключениями.
- Логировать opcode, время и close code, но вычищать token и session secrets.
- Не начинать медиапоток до Ready и выбора поддерживаемого protocol.
- На disconnect отменять старые timers, иначе параллельные heartbeat создают гонку.
После Ready проверяется UDP и аудиоформат
Voice Ready сообщает SSRC, UDP IP/port и доступные режимы шифрования. Клиент открывает UDP-соединение, выполняет IP discovery при необходимости и отправляет Select Protocol. Discord указывает, что UDP используется и для получения, и для передачи voice data; firewall или NAT должны пропускать ответные пакеты. Если бот виден в канале, но молчит, этот участок важнее повторной проверки OAuth.
Аудио для Discord кодируется Opus, два канала, 48 кГц, а transport encryption согласуется по поддерживаемому режиму. В 2026 году также учитывайте обязательную поддержку DAVE для E2EE voice: старая низкоуровневая библиотека может успешно пройти прежние шаги, но перестать быть совместимой с актуальным протоколом. Сначала обновите библиотеку и проверьте её заявление о DAVE, прежде чем писать обход самостоятельно.
Тестовая матрица отделяет права от сети
- Подключить бота к пустому тестовому каналу с минимальными Connect и Speak.
- Подтвердить пару Gateway events и свежие значения для одной попытки.
- Дождаться Voice Hello, Ready и heartbeat ACK.
- Проверить UDP discovery и Select Protocol без реального пользовательского аудио.
- Отправить короткий тестовый Opus-поток и затем корректно покинуть канал.
После исправления повторите сценарии: запрещённый Connect, разрешённый Connect без Speak, полный канал, переход между каналами и краткий сетевой разрыв. Каждый должен закончиться понятным состоянием и не оставлять «призрачное» подключение. Для отчёта нужны guild/channel IDs, версии библиотеки и gateway, close codes и времена этапов; bot token публиковать нельзя.