У голосового подключения Discord несколько независимых фаз. Команда может успешно обработаться основным Gateway, но бот не получить право `Connect`; бот может войти в канал, но остановиться до Voice Ready; либо соединение установлено, а UDP-медиа не проходит. Лог «join failed» скрывает разницу. Записывайте последнее достигнутое состояние для одной попытки.

Начните с изолированного голосового канала и одного экземпляра бота. Проверьте, что выбран именно channel ID voice-канала, бот состоит в нужном guild, канал не заполнен и итоговые права учитывают server roles и channel overwrites. Для присутствия нужно `Connect`, для отправки аудио — `Speak`; право администратора не стоит выдавать как диагностический обход.

Симптомы делят путь на четыре части

Последнее наблюдениеВероятная границаПроверка
команда принята, событий нетpermissions, limit или Gateway requestguild/channel ID, Connect, заполненность
есть Voice State, нет Voice Serverосновной Gatewayожидание обоих событий и intents библиотеки
есть token/endpoint, нет Readyvoice WebSocketсвежая сессия, URL и версия gateway
Ready есть, звука нетUDP/кодек/protocolUDP discovery, Select Protocol, Opus
работает, затем обрывheartbeat или resumeACK, 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, прежде чем писать обход самостоятельно.

Тестовая матрица отделяет права от сети

  1. Подключить бота к пустому тестовому каналу с минимальными Connect и Speak.
  2. Подтвердить пару Gateway events и свежие значения для одной попытки.
  3. Дождаться Voice Hello, Ready и heartbeat ACK.
  4. Проверить UDP discovery и Select Protocol без реального пользовательского аудио.
  5. Отправить короткий тестовый Opus-поток и затем корректно покинуть канал.

После исправления повторите сценарии: запрещённый Connect, разрешённый Connect без Speak, полный канал, переход между каналами и краткий сетевой разрыв. Каждый должен закончиться понятным состоянием и не оставлять «призрачное» подключение. Для отчёта нужны guild/channel IDs, версии библиотеки и gateway, close codes и времена этапов; bot token публиковать нельзя.

Проверенные источники