CYBERLINK BOT API

Автоматизация серверов без обходных путей

Создавайте bot users для модерации, ролей, тикетов, статистики, музыки, игровых помощников, уведомлений и внешних интеграций. Токен всегда привязан к одному account_id и работает только на серверах, куда приложение установлено владельцем или администратором.

Создать бота Открыть документацию

AuthorizationAuthorization: Bot clb_xxxxxxxxxxxxxxxxxПримерPOST /api/v1/bot/channels/42/messages

{"content":"Матч начинается через 5 минут."}

Tenant-safe

account_id определяется токеном на backend. Подменить tenant ID в запросе нельзя.

Scopes + роли

Чувствительное действие проверяет и scope токена, и реальные права роли bot user на сервере.

Install-first

Даже валидный токен не получает доступ к серверу, пока приложение явно не установлено туда.

ПОРТАЛ РАЗРАБОТЧИКА

Приложения и боты

Загрузите аватар, установите bot user на сервер, выберите минимальные scopes и выпустите токен. Полный токен показывается только один раз.

Войдите, чтобы управлять ботами

Документация ниже доступна без авторизации.

ОБЩЕЕ

Авторизация

Все Bot API методы находятся под /api/v1/bot. Передавайте токен в HTTP-заголовке. Схема — Bot, не Bearer.

Authorization: Bot clb_ВАШ_ТОКЕН
Accept: application/json
Content-Type: application/json

Токен храните только на backend. CyberLink хранит SHA-256 хэш и не может повторно показать секрет.

ПРАВА ТОКЕНА

Scopes

channels.readСписок серверов и каналовchannels.writeСоздание и удаление каналов; дополнительно требуется role permission manage_channelsmessages.readИстория сообщений и пользователи реакцийmessages.writeОтправка, изменение и удаление собственных сообщений ботаmessages.manageУдаление чужих сообщений; требуется manage_messagesdirect_messages.writeЛичные сообщения участникам сервера от имени bot usermembers.readУчастники, joined_at, текущие voice-комнатыroles.readЧтение ролейroles.writeСоздание/назначение ролей; требуется manage_rolesmoderation.writeWarn, mute, kick, ban; проверяются права роли bot userstats.readАктивность сервера и журнал Bot API модерацииmusic.writeЗапуск и управление музыкой в voice channel; требуется use_server_music

КАК СОБИРАТЬ БОТОВ

Сценарии

Антиспам / маты / ссылки

Читайте сообщения → применяйте свои фильтры → DELETE message → POST moderation с warn/mute/kick/ban.

Reaction Roles

GET users реакций конкретного сообщения → PUT роли участника. Для больших серверов опрашивайте только настроенные сообщения.

Приветствие / autorole

GET members возвращает joined_at. Новым участникам можно назначить роль, написать в канал или отправить личное приветствие через direct_messages.write.

Тикеты

Создайте служебную роль, назначьте её пользователю и создайте restricted text channel с role_ids.

Временные voice channels

GET voice показывает участников комнат. Создавайте/удаляйте voice channel через channels.write по своей логике.

GitHub / Trello / Calendar / Notion

Ваш backend принимает webhook внешнего сервиса и публикует событие через POST message.

Донаты / подписки

После подтверждения оплаты внешним провайдером назначьте VIP-роль через PUT member roles.

ИИ / игровые сервисы

Ваш backend обращается к модели или игровому API и возвращает результат сообщением. Секреты сторонних API остаются у вас.

Музыка

music.write запускает YouTube, Яндекс Музыку, VK-плейлисты и доступные CyberLink sources через серверный music pipeline.

Bot API предоставляет primitives, а не встроенные правила антиспама/экономики/ИИ: критерии, расписания, внешние API и бизнес-логика принадлежат вашему боту.

OPENAPI REFERENCE

Интерактивная документация Bot API

Методы, параметры и схемы строятся из фактического FastAPI OpenAPI. Лимит: 300 запросов/мин, burst 60 запросов за 10 сек на один bot token.

Выберите метод слева.

MESSAGES

Сообщения и реакции

GET/api/v1/bot/channels/{channel_id}/messages?limit=50

Последние доступные боту сообщения. Требуется messages.read.

Пример запроса

curl "https://cyberlinkgame.ru/api/v1/bot/channels/42/messages?limit=20" \
 -H "Authorization: Bot clb_TOKEN"

200 · application/json

[{"id":912,"channel_id":42,"body":"GG","user":{"id":17,"name":"Kayman"},"reactions":[{"emoji":"👍","count":2}]}]

POST/api/v1/bot/channels/{channel_id}/messages

Отправляет сообщение от bot user. Требуются messages.write и право send_messages / send_voice_chat.

{"content":"Рейд через 10 минут"}

200

{"id":913,"type":"message","channel_id":42,"body":"Рейд через 10 минут","user":{"id":55,"name":"RaidBot","is_bot":true}}

PATCH/api/v1/bot/channels/{channel_id}/messages/{message_id}

Редактирует только собственное сообщение бота.

{"content":"Рейд через 5 минут"}

200

{"type":"message-updated","id":913,"body":"Рейд через 5 минут"}

DELETE/api/v1/bot/channels/{channel_id}/messages/{message_id}

Своё сообщение: messages.write. Чужое: messages.manage + server permission manage_messages.

200

{"ok":true,"type":"message-deleted","id":913,"channel_id":42,"user_id":17}

GET/api/v1/bot/channels/{channel_id}/messages/{message_id}/reactions

Показывает не только счётчик, но и пользователей каждой реакции — база для Reaction Roles и голосований.

200

{"message_id":913,"reactions":[{"emoji":"✅","count":2,"users":[{"id":17,"name":"Kayman","username":"kayman","bot":false}]}]}

POST/api/v1/bot/channels/{channel_id}/messages/{message_id}/reactions

Поставить или снять реакцию от имени bot user. Scope: messages.write. Поддерживаются Unicode и серверные custom emoji токены.

{"emoji":"✅"}

200

{"type":"message-reactions","message_id":913,"reactions":[{"emoji":"✅","count":3}]}

POST/api/v1/bot/servers/{server_id}/members/{user_id}/dm

Отправляет личное сообщение участнику этого сервера. Scope: direct_messages.write. Нельзя писать пользователям другого tenant/server.

{"content":"Добро пожаловать! Правила: ..."}

200

{"ok":true,"conversation_id":91,"message":{"id":501,"body":"Добро пожаловать! Правила: ..."}}

ROLES

Роли

GET/api/v1/bot/servers/{server_id}/roles

Требуется roles.read.

{"items":[{"id":8,"name":"VIP","color":"#ffd24a","permissions":["send_messages"],"display_separately":true,"position":20}]}

POST/api/v1/bot/servers/{server_id}/roles

Создаёт роль. Бот не может выдать новой роли permissions, которых нет у самого bot user.

{"name":"VIP","color":"#ffd24a","permissions":["send_messages","join_voice"],"display_separately":true}

200

{"id":8,"server_id":1,"name":"VIP","permissions":["send_messages","join_voice"]}

PUT/api/v1/bot/servers/{server_id}/members/{user_id}/roles

Полностью заменяет набор пользовательских custom roles. Владелец сервера защищён.

{"role_ids":[8,12]}

{"ok":true,"user_id":17,"role_ids":[8,12]}

CHANNELS / TICKETS

Создание каналов

POST/api/v1/bot/servers/{server_id}/channels

Создаёт text/voice channel. Для тикета включите restricted и передайте роли, которым он видим.

{"name":"ticket-kayman","kind":"text","restricted":true,"role_ids":[12]}

{"id":81,"server_id":1,"group_id":6,"name":"ticket-kayman","kind":"text","private":true,"role_ids":[12]}

DELETE/api/v1/bot/servers/{server_id}/channels/{channel_id}

Удаляет канал. Последний текстовый канал сервера удалить нельзя.

{"ok":true,"channel_id":81}

MODERATION

Предупреждения, муты, кики и баны

POST/api/v1/bot/servers/{server_id}/members/{user_id}/moderation

action: warn, mute, unmute, kick, ban, unban. Временный mute блокирует текст, voice chat, вход в voice и стрим до срока. Ban не позволяет повторно вступить.

{"action":"mute","reason":"Повторный спам ссылками","duration_seconds":3600}

200

{"ok":true,"action":"mute","user_id":17,"expires_at":"2026-09-09T12:00:00Z"}

Права роли

warn → manage_messages
mute → mute_members
kick → kick_members
ban → ban_members

GET/api/v1/bot/servers/{server_id}/moderation?limit=50

Журнал действий, созданных Bot API. Доступен с moderation.write или stats.read.

{"items":[{"id":31,"actor_user_id":55,"target_user_id":17,"action":"mute","reason":"spam","expires_at":"...","created_at":"..."}]}

VOICE / MUSIC

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

GET/api/v1/bot/servers/{server_id}/voice

Текущие voice rooms и participants. Подходит для временных каналов, игровых лобби и realtime-панелей с безопасным polling.

{"server_id":1,"rooms":[{"channel_id":22,"count":2,"active_since_ms":1788,"participants":[{"user_id":17,"display_name":"Kayman"}]}]}

POST/api/v1/bot/servers/{server_id}/music/play

Запускает server music без необходимости держать отдельный bot WebRTC client. Используется тот же CyberLink resolver, что и пользовательским плеером.

{"channel_id":22,"source_kind":"external","source_url":"https://music.yandex.ru/album/123/track/456"}

Также поддерживаются youtube, CyberLink attachments и mixed queue.

200

{"server_id":1,"channel_id":22,"status":"playing","title":"...","revision":7,"queue_count":1}

POST/api/v1/bot/servers/{server_id}/music/control

{"channel_id":22,"action":"next"}

actions: pause, resume, stop, next, previous, seek, play_index, reorder_queue.

{"status":"playing","revision":8,"queue_index":1}

STATS

Статистика

GET/api/v1/bot/servers/{server_id}/stats

Количество участников/online, текущий voice online, сообщения за 24h/7d/30d и число активных авторов за 7 дней.

{"server_id":1,"members":123,"online":28,"voice_online":12,"messages":{"24h":631,"7d":4102,"30d":14400},"active_authors_7d":64,"generated_at":"..."}

GET/api/v1/bot/servers/{server_id}/members

Содержит joined_at и communication_disabled_until. Это позволяет строить autorole/welcome-процессы без передачи системных секретов пользователям.

[{"id":17,"name":"Kayman","username":"kayman","bot":false,"role":"member","joined_at":"...","communication_disabled_until":null}]

ERRORS

Ошибки и безопасность

400 / 422Некорректные поля, ID или действие.401Токен отсутствует, неверен или отозван.403Недостаточный scope, role permission или доступ к объекту.404Объект недоступен в tenant бота или бот не установлен.409Конфликт состояния/лимита.

Не передавайте account_id как источник доверия: Bot API его не принимает. Tenant, application и bot user восстанавливаются только из хэша токена.