Боты и APIv216

Сервис Vortex (https://vortex-voice.com) · Редакция от 01.09.2026

Бот в Vortex — это обычная учётная запись, которой управляет программа: скрипт подключается к серверу по тому же WebSocket-протоколу, что и браузерный клиент. Отдельной регистрации для ботов не нужно: при первом подключении сервер сам выдаёт учётный токен, а дальше бот может читать команды в чатах, отвечать на сообщения и даже заходить в голосовые каналы со своим звуком.

На этой странице: готовый музыкальный бот из коробки и справочник Bot API для тех, кто хочет написать своего.

1. Музыкальный бот — быстрый старт

В комплекте с сервером идёт готовый бот bot/music_bot.py: по команде !play он входит в голосовой канал и играет музыку с YouTube (по ссылке или по названию) для всех участников. Работает на Linux и Windows.

Поставьте зависимости: pip install -r bot/requirements-bot.txt и ffmpeg (apt install ffmpeg на Linux, winget install Gyan.FFmpeg на Windows).
Запустите: python bot/music_bot.py. При первом старте бот создаст себе учётку и сохранит токен в bot_identity.json — не теряйте этот файл.
Пригласите бота на сервер: напишите ему в личку !join <ссылка-приглашение> (создать: настройки сервера → «Пригласить»). Ссылку-приглашение можно просто прислать боту в личку командой — он поймёт.
Зайдите в голосовой канал и напишите в текстовом канале сервера или в личке боту: !play кино 2026.

Переменные окружения

Переменная	По умолчанию	Зачем
`VORTEX_SERVER`	`wss://vortex-voice.com`	Адрес сервера Vortex, к которому подключается бот.
`VORTEX_BOT_NAME`	`🎵 Музыкальный бот`	Отображаемое имя бота. Эмодзи в начале имени становится его аватаркой.
`VORTEX_BOT_PREFIX`	`!`	Префикс команд (`!play`, `?play` и т.п.).
`VORTEX_BOT_INVITE`	—	Ссылка-приглашение: бот сам вступит на сервер при старте, без `!join`.
`VORTEX_YTDLP` / `VORTEX_FFMPEG`	поиск в PATH	Явные пути к yt-dlp и ffmpeg, если бот их не находит сам.

Команды

Команда	Что делает
`!join <ссылка\|код>`	Вступить на сервер или в приватный канал по приглашению.
`!play <url\|название>`	Поставить трек; если что-то уже играет — добавить в очередь. Ссылка-приглашение Vortex вместо музыки — бот просто вступит по ней.
`!skip` / `!stop`	��ледующий трек / остановить всё и очистить очередь.
`!pause` / `!resume`	Пауза / продолжить.
`!queue`	Показать текущий трек и очередь.
`!vol 0-200`	Громкость в процентах (по умолчанию 80).
`!leave`	Выйти из голосового канала.

Команды слышны и в текстовых каналах серверов, где бот — участник, и в личных сообщениях с ботом. Один процесс бота играет в одном голосовом канале одновременно; SFU-каналы пока не поддерживаются, только обычные (mesh).

2. Bot API: свой бот по WebSocket

Протокол — тот же, что у браузерного клиента: JSON-сообщения по WebSocket. Подключение: wss://<ваш-сервер>/ws.

Подключение и авторизация

Первым сообщением бот отправляет hello. При первом входе сервер вернёт welcome со свежим auth_token — сохраните его и присылайте в следующий раз, иначе учётку бота сможет перехватить первый встречный (trust on first use).

// → первое сообщение после подключения
{
  "type": "hello",
  "user_id": "bot-6b944944…",        // стабильный id бота (генерируется один раз)
  "username": "🎵 Мой бот",
  "avatar_color": "#7c5cff",
  "auth_token": ""                    // пусто при первом входе, дальше — из сохранённого
}

// ← ответ сервера
{ "type": "welcome", "auth_token": "…", "users": […], "channels": […] }

Сообщения

Тип	Направление	Назначение
`chat_message`	↕	Сообщение в текстовый канал сервера: `{"type":"chat_message","channel_id":"…","content":"текст"}`. Входящие приходят только из каналов серверов, где бот участник.
`conversation_message`	↕	Личка/групповой чат: `{"type":"conversation_message","conversation_id":"…","content":"текст"}`.
`conversation_created`	←	Кто-то открыл личку с ботом — удобно поздороваться и подсказать команды.
`presence`	←	Обновления списка пользователей (статусы, текущий голосовой канал).
`join_server` / `join_private_channel`	→	Вступить по приглашению: `{"type":"join_server","invite_code":"…"}`. Код — из ссылки `?invite=…&kind=server\|channel`.
`server_joined` / `channel_created` / `error`	←	Результаты вступления и ошибки (неверный код, бан и т.п.).

Голосовые каналы и звук

В голосе бот — обычный WebRTC-пир. Библиотека aiortc (Python) покрывает весь тракт: бот отвечает на офферы участников и офферит сам тем, кто зашёл позже.

→ {"type":"voice_join","channel_id":"…"}      // войти в голосовой канал
← {"type":"voice_peer_join","peer_id":"…"}   // кто-то зашёл — офферим ему сами
← {"type":"webrtc_offer","from":"…","sdp":{…},"kind":"audio"}
→ {"type":"webrtc_answer","target":"…","sdp":{…},"kind":"audio"}
↕ {"type":"webrtc_ice", …}                    // ICE-кандидаты в обе стороны
→ {"type":"voice_leave"}                      // выйти

Свой аудиотрек бот крутит вместо микрофона: 48 кГц, стерео, кадры по 20 мс. Входящие дорожки участников нужно вычитывать (иначе раздувает джиттер-буфер), но обрабатывать их не обязательно.

Качество музыки. Если музыка через бота «дырявится» и пропадают тихие звуки — это не шумодав слушателя, а речевой режим Opus-кодировщика (application="voip", 96 кбит/с) в aiortc по умолчанию. С версии v216 штатный music_bot.py сам переводит кодировщик в музыкальный режим application="audio" с битрейтом 192 кбит/с. В своём боте сделайте то же самое — и проверьте, что у слушателей ничего не зажато в настройках громкости.

3. Ограничения и правила

Лимит входов: до 40 hello в минуту с одного IP; при превышении соединение закрывается с причиной rate_limited.
Текст сообщения — до ~2000 символов; более длинные обрезайте сами.
Бот видит только те серверы, куда его впустили приглашением, и свои личные чаты.
Не используйте ботов для спама и флуда: аккаунты-нарушители блокируются, а удалённый администратором аккаунт не воскресает повторным подключением.
Один аккаунт может держать несколько одновременных подключений (несколько процессов с одним user_id) — старые соединения не вытесняются.

Готовый пример, реализующий всё описанное выше, — bot/music_bot.py в архиве сервера, рядом лежит bot/README_BOT.md с подробной инструкцией по установке.