Voice API

См. также Voice playback — концептуальный обзор.

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

Проиграть аудио

POST /api/bot/spaces/{space_id}/voice/{channel_id}/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/track.mp3", "loop": false, "volume": 100}'

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

{
  "session_id": "019c3851-...", // идентификатор сессии проигрывания
  "status": "playing"
}

source_urlstringrequired

Публичная http(s)-ссылка на аудио — трек, плейлист, HLS, Icecast или файл. Ссылка валидируется (SSRF-защита, как для webhook-URL) и имеет лимит длины. Приватные и локальные адреса отклоняются (400).

loopbooleandefault: false

Зациклить источник. По умолчанию false.

volumeintegerdefault: 100

Громкость проигрывания в процентах. По умолчанию 100.

Требует:

• Scope: voice.publish_audio
• channel_id входит в allowed_channel_ids
• Бот в статусе active

Источник аудио — на стороне разработчика. Рекомендации по подготовке ссылки см. в Audio source.

Остановить проигрывание

POST /api/bot/spaces/{space_id}/voice/{channel_id}/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.

Загруженность voice-каналов

GET /api/bot/spaces/{space_id}/voice · scope voice.join

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

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

[
  { "channel_id": "019c3851-...", "participant_count": 2, "bot_present": false }
]

Возвращает все allowed_channels бота — только число участников (participant_count) и факт присутствия самого бота (bot_present). Идентификации участников (user_id / display_name) не отдаются (privacy).

SDK-шорткат «найти занятый канал»:

ch_id = bot.client.find_occupied_voice_channel(space_id=space_id)

Ошибки

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

Дальше

Voice playback

Концептуальный обзор: как бот проигрывает аудио в канале.

Audio source

Как подготовить ссылку на источник аудио.