BANNGRU Bot API
BANNGRU Bot API полностью совместим с discord.js и другими Discord-ботами. Подключите существующего бота к BANNGRU, изменив только API endpoints — код остаётся прежним!
Обзор
BANNGRU поддерживает Bot API слой, совместимый с популярными бот-фреймворками (discord.js и др.), что позволяет подключать ботов к платформе с минимальными изменениями.
Реализовано:
- REST API v10 (
/api/v10/*) - Gateway WebSocket (
/bot-gw) — опкоды 0–11 - Маппинг сущностей: серверы → guilds, каналы → channels, участники → members
- Поддержка Intents для фильтрации событий
- Slash-команды с автодополнением
- Webhooks для real-time событий
- Подключение к голосовым каналам
- Личные сообщения пользователям
Discord.js совместимость
BANNGRU Bot API полностью совместим с discord.js. Для подключения достаточно переопределить API endpoints:
const { Client, GatewayIntentBits } = require('discord.js');
const BANNGRU_API = 'https://web.banngru.ru/api/v10';
const BANNGRU_GATEWAY = 'wss://web.banngru.ru/bot-gw';
const client = new Client({
intents: [
GatewayIntentBits.Guilds,
GatewayIntentBits.GuildMessages,
GatewayIntentBits.MessageContent,
],
rest: {
api: BANNGRU_API,
version: '', // Отключаем версионирование
},
});
client.on('ready', () => {
console.log(`Бот ${client.user.tag} подключён к BANNGRU!`);
});
client.on('messageCreate', async (message) => {
if (message.author.bot) return;
if (message.content === '!ping') {
await message.reply('Понг! 🏓');
}
});
client.login('ВАШ_BANNGRU_BOT_ТОКЕН');
Gateway URL автоматически запрашивается через
GET /api/v10/gateway/bot. BANNGRU возвращает правильный URL.
Авторизация
Все запросы от бота должны содержать заголовок авторизации:
Authorization: Bot YOUR_BOT_TOKENТокен показывается только при создании. При компрометации — регенерируйте через
/api/bots/:botId/regenerate-token
Создание бота
Через веб-интерфейс:
- Зайдите на https://web.banngru.ru
- Перейдите в настройки → Боты → Создать бота
- Укажите username, display_name, описание
- Скопируйте токен (он показывается только при создании)
Через API:
curl -X POST https://web.banngru.ru/api/bots \
-H "Authorization: Bearer <твой_jwt_токен>" \
-H "Content-Type: application/json" \
-d '{
"username": "mybot",
"display_name": "Мой Бот",
"description": "Тестовый бот",
"is_public": true
}'
Ответ:
{
"success": true,
"bot": {
"id": 10,
"username": "mybot",
"display_name": "Мой Бот",
"token": "a1b2c3d4e5f6...64_символа_hex",
"is_active": true
}
}
Токен показывается только один раз при создании. При компрометации регенерируйте через
/api/bots/:botId/regenerate-token
Добавление бота на сервер
Бот должен быть добавлен на сервер (guild) через BANNGRU, чтобы иметь к нему доступ.
Через веб-интерфейс:
- Зайдите в настройки сервера → Боты → Добавить бота
- Выберите бота из списка или введите его ID
Через API (от имени владельца/админа сервера):
curl -X POST https://web.banngru.ru/api/servers/<serverId>/bots/<botId>/install \
-H "Authorization: Bearer <jwt_токен_владельца>"
API эндпоинты
Управление ботом (Bearer Token)
| Метод | Эндпоинт | Описание |
|---|---|---|
| POST | /api/bots/create | Создать бота |
| GET | /api/bots | Список ваших ботов |
| GET | /api/bots/:botId | Информация о боте |
| PUT | /api/bots/:botId | Обновить бота |
| DELETE | /api/bots/:botId | Удалить бота |
| POST | /api/bots/:botId/regenerate-token | Регенерировать токен |
| POST | /api/bots/:botId/webhook | Установить webhook URL |
| POST | /api/bots/:botId/commands | Регистрация команд |
| GET | /api/bots/:botId/commands | Получить команды |
| POST | /api/bots/:botId/avatar | Загрузить аватар |
Bot Token API (Authorization: Bot TOKEN)
| Метод | Эндпоинт | Описание |
|---|---|---|
| GET | /api/v10/gateway | URL Gateway |
| GET | /api/v10/gateway/bot | URL Gateway для ботов (с лимитами) |
| GET | /api/v10/users/@me | Информация о текущем боте |
| GET | /api/v10/guilds/:id | Информация о сервере |
| GET | /api/v10/guilds/:id/channels | Каналы сервера |
| GET | /api/v10/guilds/:id/members | Участники сервера |
| GET | /api/v10/channels/:id | Информация о канале |
| GET | /api/v10/channels/:id/messages | Получение сообщений |
| POST | /api/v10/channels/:id/messages | Отправка сообщения |
| PATCH | /api/v10/channels/:id/messages/:msgId | Редактирование сообщения |
| DELETE | /api/v10/channels/:id/messages/:msgId | Удаление сообщения |
| PUT | /api/v10/channels/:id/messages/:msgId/reactions/:emoji/@me | Добавить реакцию |
| POST | /api/v10/channels/:id/typing | Индикатор набора текста |
| GET | /api/v10/applications/:id/commands | Глобальные команды |
| POST | /api/v10/applications/:id/commands | Создать глобальную команду |
| PUT | /api/v10/applications/:id/guilds/:guildId/commands | Перезаписать команды сервера |
| POST | /api/v10/interactions/:id/:token/callback | Ответ на interaction |
Публичные боты
| Метод | Эндпоинт | Описание |
|---|---|---|
| GET | /api/bots/public | Список публичных ботов |
| GET | /api/bots/public/search?query= | Поиск публичных ботов |
| GET | /api/servers/:serverId/bots | Боты на сервере |
Gateway WebSocket
BANNGRU поддерживает Gateway WebSocket для real-time событий. Подключение: wss://web.banngru.ru/bot-gw
Отправляемые сервером события (DISPATCH, opcode 0):
| Событие | Описание |
|---|---|
READY | Бот авторизован, содержит список guilds |
RESUMED | Сессия восстановлена |
GUILD_CREATE | Информация о сервере (каналы, роли, участники) |
MESSAGE_CREATE | Новое сообщение в канале |
INTERACTION_CREATE | Slash-команда от пользователя |
VOICE_STATE_UPDATE | Изменение голосового состояния |
VOICE_SERVER_UPDATE | Информация о голосовом сервере |
GUILD_MEMBERS_CHUNK | Ответ на REQUEST_GUILD_MEMBERS |
Принимаемые от клиента opcodes:
| Opcode | Название | Описание |
|---|---|---|
| 1 | HEARTBEAT | Поддержание соединения |
| 2 | IDENTIFY | Авторизация (передаётся токен) |
| 3 | PRESENCE_UPDATE | Обновление статуса |
| 4 | VOICE_STATE_UPDATE | Подключение к голосовому каналу |
| 6 | RESUME | Восстановление сессии |
| 8 | REQUEST_GUILD_MEMBERS | Запрос списка участников |
Пример IDENTIFY:
{
"op": 2,
"d": {
"token": "Bot ВАШ_ТОКЕН",
"intents": 513,
"properties": {
"os": "linux",
"browser": "discord.js",
"device": "discord.js"
}
}
}
Маппинг сущностей
BANNGRU автоматически преобразует свои сущности в формат Discord API:
| BANNGRU | API формат | Примечание |
|---|---|---|
| Сервер (servers) | Guild | Полный маппинг полей |
| Канал text | GUILD_TEXT (type 0) | |
| Канал voice | GUILD_VOICE (type 2) | |
| Канал category | GUILD_CATEGORY (type 4) | |
| Участник (server_members) | GuildMember | С ролями и никнеймом |
| Сообщение (messages) | Message | Включая embeds, components |
| Бот (bots) | User (bot=true) | discriminator всегда "0000" |
| Роль (roles) | Role | С permissions |
Сообщения
Отправка сообщения (discord.js):
// Через discord.js
const channel = await client.channels.fetch('channel_id');
await channel.send('Привет! 👋');
// С embed
const embed = new EmbedBuilder()
.setTitle('Заголовок')
.setDescription('Описание')
.setColor(0x5865F2);
await channel.send({ embeds: [embed] });
// С кнопками
const row = new ActionRowBuilder()
.addComponents(
new ButtonBuilder()
.setCustomId('yes')
.setLabel('✅ Да')
.setStyle(ButtonStyle.Primary),
new ButtonBuilder()
.setCustomId('no')
.setLabel('❌ Нет')
.setStyle(ButtonStyle.Danger)
);
await channel.send({ content: 'Выберите:', components: [row] });
Редактирование сообщения:
const message = await channel.messages.fetch('message_id');
await message.edit('Обновлённый текст');
Удаление сообщения:
await message.delete();
Slash-команды
BANNGRU поддерживает регистрацию и обработку slash-команд через Bot API.
Регистрация команд (discord.js):
const { REST, Routes, SlashCommandBuilder } = require('discord.js');
const rest = new REST({ version: '' })
.setToken('ВАШ_BANNGRU_BOT_ТОКЕН');
rest.options.api = 'https://web.banngru.ru/api/v10';
const commands = [
new SlashCommandBuilder()
.setName('ping')
.setDescription('Проверка связи'),
new SlashCommandBuilder()
.setName('say')
.setDescription('Бот скажет что-то')
.addStringOption(opt =>
opt.setName('text').setDescription('Текст').setRequired(true)
),
];
const BOT_ID = 'ваш_bot_id';
const GUILD_ID = 'id_сервера';
(async () => {
await rest.put(
Routes.applicationGuildCommands(BOT_ID, GUILD_ID),
{ body: commands.map(c => c.toJSON()) }
);
console.log('Команды зарегистрированы!');
})();
Обработка slash-команд:
client.on('interactionCreate', async (interaction) => {
if (!interaction.isChatInputCommand()) return;
if (interaction.commandName === 'ping') {
await interaction.reply('Понг! 🏓');
}
if (interaction.commandName === 'say') {
const text = interaction.options.getString('text');
await interaction.reply(text);
}
});
Intents
BANNGRU полностью поддерживает Bot Gateway Intents. Бот получает только те события, которые соответствуют запрошенным intents при IDENTIFY.
Без
MessageContent intent бот получит MESSAGE_CREATE, но поля content, embeds, attachments будут пустыми (кроме DM, упоминаний бота и собственных сообщений).
Поддерживаемые intents:
| Intent | Бит | События |
|---|---|---|
| GUILDS | 1 << 0 | GUILD_CREATE, CHANNEL_CREATE и т.д. |
| GUILD_MEMBERS | 1 << 1 | GUILD_MEMBER_ADD/UPDATE/REMOVE (privileged) |
| GUILD_MODERATION | 1 << 2 | GUILD_BAN_ADD/REMOVE |
| GUILD_VOICE_STATES | 1 << 7 | VOICE_STATE_UPDATE |
| GUILD_PRESENCES | 1 << 8 | PRESENCE_UPDATE (privileged) |
| GUILD_MESSAGES | 1 << 9 | MESSAGE_CREATE/UPDATE/DELETE |
| GUILD_MESSAGE_REACTIONS | 1 << 10 | MESSAGE_REACTION_* |
| GUILD_MESSAGE_TYPING | 1 << 11 | TYPING_START |
| DIRECT_MESSAGES | 1 << 12 | MESSAGE_* в DM |
| MESSAGE_CONTENT | 1 << 15 | Доступ к content сообщений (privileged) |
Пример использования:
const client = new Client({
intents: [
GatewayIntentBits.Guilds, // GUILD_CREATE и т.д.
GatewayIntentBits.GuildMessages, // MESSAGE_CREATE в каналах
GatewayIntentBits.MessageContent, // content, embeds, attachments
],
});
Rate Limits
BANNGRU имеет более строгие лимиты по сравнению со стандартным Discord API:
| Эндпоинт | Discord | BANNGRU |
|---|---|---|
| Глобальный лимит | 50 req/sec | 25 req/sec |
| POST messages (на канал) | 5 / 5 сек | 3 / 5 сек |
| DELETE messages (на канал) | 5 / 1 сек | 3 / 2 сек |
| PATCH messages (на канал) | 5 / 5 сек | 3 / 5 сек |
| PUT reactions | 1 / 0.25 сек | 1 / 1 сек |
| Typing | 5 / 5 сек | 2 / 5 сек |
| GET members | 10 / 10 сек | 5 / 10 сек |
| PUT commands (bulk) | 2 / мин | 1 / мин |
| Gateway events | 120 / мин | 60 / мин |
| Gateway IDENTIFY | 1 / 5 сек | 1 / 10 сек |
При превышении лимита REST API возвращает 429 Too Many Requests с заголовками:
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 0
X-RateLimit-Reset-After: 2.5
Retry-After: 3
При превышении Gateway лимита соединение закрывается с кодом 4008.
Webhooks (Native BANNGRU API)
Помимо Discord.js совместимости, BANNGRU предоставляет нативный Webhook API для получения событий.
При использовании discord.js события приходят через Gateway WebSocket. Webhooks нужны только если вы используете нативный BANNGRU API без discord.js.
Типы событий:
| Тип | Описание |
|---|---|
message | Новое сообщение в канале с ботом |
command | Вызов команды бота |
callback | Нажатие inline-кнопки |
member_join | Пользователь присоединился к серверу |
member_leave | Пользователь покинул сервер |
Установка webhook URL:
curl -X POST https://web.banngru.ru/api/bots/:botId/webhook \
-H "Authorization: Bearer <user_token>" \
-H "Content-Type: application/json" \
-d '{"url": "https://your-server.com/webhook"}'
Верификация запросов:
const crypto = require('crypto');
function verifySignature(body, signature, token) {
const expected = crypto.createHmac('sha256', token)
.update(JSON.stringify(body))
.digest('hex');
return signature === expected;
}
// Проверка в обработчике
app.post('/webhook', (req, res) => {
const signature = req.headers['x-bot-signature'];
if (!verifySignature(req.body, signature, BOT_TOKEN)) {
return res.status(401).send('Invalid signature');
}
// Обработка события
res.send('OK');
});
Голосовые каналы
BANNGRU поддерживает подключение ботов к голосовым каналам через Gateway API.
Подключение к голосовому каналу (discord.js):
const { joinVoiceChannel } = require('@discordjs/voice');
const connection = joinVoiceChannel({
channelId: voiceChannel.id,
guildId: voiceChannel.guild.id,
adapterCreator: voiceChannel.guild.voiceAdapterCreator,
});
console.log('Подключён к голосовому каналу!');
Отключение от голосового канала:
connection.destroy();
console.log('Отключён от голосового канала');
BANNGRU использует mediasoup для голосовых каналов. Полноценный голосовой протокол (UDP, Opus) работает через BANNGRU mediasoup, а не через стандартный Discord voice protocol.
Личные сообщения
Отправка DM пользователю (discord.js):
// Получить пользователя
const user = await client.users.fetch('user_id');
// Отправить DM
await user.send('Привет! Это личное сообщение от бота.');
// С embed
const embed = new EmbedBuilder()
.setTitle('Уведомление')
.setDescription('Важное сообщение для вас')
.setColor(0x00ff88);
await user.send({ embeds: [embed] });
Обработка DM от пользователей:
client.on('messageCreate', async (message) => {
// Проверяем, что это DM (не в канале сервера)
if (message.channel.type === ChannelType.DM) {
console.log(`DM от ${message.author.tag}: ${message.content}`);
await message.reply('Спасибо за сообщение!');
}
});
Примеры кода
Полный discord.js бот для BANNGRU:
const { Client, GatewayIntentBits, REST, Routes, SlashCommandBuilder, EmbedBuilder } = require('discord.js');
const BOT_TOKEN = process.env.BOT_TOKEN || 'ваш_токен';
const BOT_ID = process.env.BOT_ID || 'ваш_bot_id';
const API_BASE = 'https://web.banngru.ru/api/v10';
// Создаём клиент
const client = new Client({
intents: [
GatewayIntentBits.Guilds,
GatewayIntentBits.GuildMessages,
GatewayIntentBits.MessageContent,
],
rest: {
api: API_BASE,
version: '',
},
});
// Регистрация команд при старте
client.once('ready', async () => {
console.log(`✅ ${client.user.username} подключён к BANNGRU!`);
const rest = new REST({ version: '' }).setToken(BOT_TOKEN);
rest.options.api = API_BASE;
const commands = [
new SlashCommandBuilder().setName('ping').setDescription('Понг!'),
new SlashCommandBuilder().setName('server').setDescription('Инфо о сервере'),
new SlashCommandBuilder()
.setName('echo')
.setDescription('Повторить текст')
.addStringOption(o => o.setName('text').setDescription('Текст').setRequired(true)),
];
// Регистрируем для каждого сервера
for (const guild of client.guilds.cache.values()) {
try {
await rest.put(
Routes.applicationGuildCommands(BOT_ID, guild.id),
{ body: commands.map(c => c.toJSON()) }
);
console.log(` Команды зарегистрированы на ${guild.name}`);
} catch (e) {
console.error(` Ошибка регистрации на ${guild.name}:`, e.message);
}
}
});
// Обработка сообщений
client.on('messageCreate', async (msg) => {
if (msg.author.bot) return;
if (msg.content === '!ping') {
await msg.reply('🏓 Понг!');
}
});
// Обработка slash-команд
client.on('interactionCreate', async (interaction) => {
if (!interaction.isChatInputCommand()) return;
switch (interaction.commandName) {
case 'ping':
await interaction.reply('🏓 Понг!');
break;
case 'server':
const embed = new EmbedBuilder()
.setTitle(interaction.guild.name)
.setColor(0x5865F2)
.addFields(
{ name: 'ID', value: interaction.guild.id, inline: true },
{ name: 'Участников', value: String(interaction.guild.memberCount), inline: true },
);
await interaction.reply({ embeds: [embed] });
break;
case 'echo':
const text = interaction.options.getString('text');
await interaction.reply(text);
break;
}
});
client.login(BOT_TOKEN);
Запуск:
BOT_TOKEN=ваш_токен BOT_ID=10 node bot.js
Отладка
Проверка подключения:
# Проверить Gateway URL
curl https://web.banngru.ru/api/v10/gateway
# Проверить авторизацию
curl https://web.banngru.ru/api/v10/users/@me \
-H "Authorization: Bot ВАШ_ТОКЕН"
# Получить серверы бота
curl https://web.banngru.ru/api/v10/gateway/bot \
-H "Authorization: Bot ВАШ_ТОКЕН"
Частые проблемы:
| Проблема | Решение |
|---|---|
401 Unauthorized | Проверьте токен, убедитесь что бот is_active = true |
403 Missing Access | Бот не добавлен на сервер (нет записи в bot_instances) |
| Gateway не подключается | Проверьте URL: wss://web.banngru.ru/bot-gw |
| Не приходят события | Убедитесь что бот прошёл IDENTIFY и получил READY |
| Slash-команды не работают | Зарегистрируйте команды через PUT commands API |
| Пустой content в сообщениях | Добавьте MessageContent intent |
• Sharding не требуется (всегда 1 shard)
• Threads, Forums, Stage channels не поддерживаются
• File uploads через REST API пока не поддерживаются
• Голосовой протокол работает через BANNGRU mediasoup, а не через внешний voice protocol
Лимиты и ограничения
Общие лимиты:
| Параметр | Значение |
|---|---|
| Ботов на пользователя | 25 |
| Символов в сообщении | 4000 |
| Кнопок в сообщении | 10 |
| Команд на бота | 50 |
| Размер аватара | 8 MB |
| Username | 3-80 символов (латиница/цифры/_) |
| Display name | 1-100 символов |
| Description | до 500 символов |
Особенности и ограничения:
- Sharding: Не требуется, всегда 1 shard
- Threads, Forums, Stage channels: Не поддерживаются
- File uploads: Через REST API пока не поддерживаются, используйте BANNGRU S3 API
- Webhooks (Discord-style): Используйте нативный BANNGRU webhook API
- Голосовой протокол: Работает через BANNGRU mediasoup, а не через внешний voice protocol
- Permissions: Упрощённая модель, все проверки через bot_instances
- Intents: Полностью поддерживаются, фильтруют события на Gateway
При разработке бота используйте discord.js — это обеспечит максимальную совместимость и упростит миграцию между платформами.