Playback API

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

Все вызовы — bot-facing, с заголовком Authorization: Bot <token>.

POST /play

Запустить воспроизведение источника в голосовом канале.

curl -X POST https://api.reasonspace.ru/api/bot/spaces/{space_id}/voice/{channel_id}/play \
  -H "Authorization: Bot bot_..." \
  -H "Content-Type: application/json" \
  -d '{"source_url": "https://example.com/stream.mp3", "loop": false, "volume": 100}'

session = await bot.client.voice_play(
    channel_id,
    "https://example.com/stream.mp3",
    space_id=space_id,
    loop=False,
    volume=100,
)

{
  "session_id": "...",
  "status": "playing"
}

Тело запроса

source_urlstringrequired

Публичная http(s)-ссылка на аудио: трек, плейлист, HLS, Icecast или файл. Платформа сама скачивает и проигрывает источник — боту не нужен ни плеер, ни медиа-сессия.

Ссылка валидируется так же, как webhook-URL (SSRF-защита), и ограничена по длине. Приватные и локальные адреса отклоняются с 400.

loopbooleandefault: false

Зациклить источник. По умолчанию false — после окончания воспроизведение останавливается.

volumeintegerdefault: 100

Громкость воспроизведения, 0–100. По умолчанию 100.

Поля ответа

session_idstring

Идентификатор сессии воспроизведения. Один активный источник на канал.

statusstring

Статус сессии (например, playing).

Требования

• Scope voice.publish_audio
• channel_id ∈ allowed_channel_ids
• Бот в состоянии active

POST /stop

Остановить воспроизведение в канале. Тело не требуется.

curl -X POST https://api.reasonspace.ru/api/bot/spaces/{space_id}/voice/{channel_id}/stop \
  -H "Authorization: Bot bot_..."

await bot.client.voice_stop(channel_id, space_id=space_id)

Ответ — 204 No Content.

GET /voice

Узнать занятость каналов Space — без идентификаций участников.

curl https://api.reasonspace.ru/api/bot/spaces/{space_id}/voice \
  -H "Authorization: Bot bot_..."

overview = await bot.client.voice_overview(space_id)
channel = bot.client.find_occupied_voice_channel(space_id)

[
  {
    "channel_id": "...",
    "participant_count": 3,
    "bot_present": true
  }
]

Возвращается только загруженность каналов: сколько участников и присутствует ли сам бот. Identity участников не раскрывается — это намеренное ограничение приватности. Требует scope voice.join.

Privacy

• Бот не подключается к голосовому каналу и не получает медиа — платформа проигрывает источник односторонне.
• У бота нет принимающей сессии, поэтому он не может слышать участников. Это свойство архитектуры, а не соглашение.
• Бот никогда не модератор: kick, mute и запись через этот API недоступны.

Подробнее: Privacy.

Errors

HTTP	Что значит
403	Нет нужного scope (voice.publish_audio для /play, voice.join для /voice) либо voice выключен на сервере
400	Невалидный или небезопасный source_url (приватный/локальный адрес, превышение лимита длины)
501	Voice playback не сконфигурирован на сервере
429	Превышен лимит вызовов (rate-limit)

Дальше

Audio source

Какие источники подходят и как их подготовить.

Presence

Как бот отображается в voice и что он видит про других.