Bot API Documentation Обновлено: 11.03.2026

BANNGRU Bot API

v2.0 Discord.js Compatible REST API v10 Gateway WebSocket Intents Support
Discord.js совместимость
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:

JavaScript
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.

Авторизация

Все запросы от бота должны содержать заголовок авторизации:

HTTP Header
Authorization: Bot YOUR_BOT_TOKEN
Важно!
Токен показывается только при создании. При компрометации — регенерируйте через /api/bots/:botId/regenerate-token

Создание бота

Через веб-интерфейс:

  • Зайдите на https://web.banngru.ru
  • Перейдите в настройки → Боты → Создать бота
  • Укажите username, display_name, описание
  • Скопируйте токен (он показывается только при создании)

Через API:

Bash
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
  }'

Ответ:

JSON
{
  "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 (от имени владельца/админа сервера):

Bash
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/gatewayURL Gateway
GET/api/v10/gateway/botURL 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_CREATESlash-команда от пользователя
VOICE_STATE_UPDATEИзменение голосового состояния
VOICE_SERVER_UPDATEИнформация о голосовом сервере
GUILD_MEMBERS_CHUNKОтвет на REQUEST_GUILD_MEMBERS

Принимаемые от клиента opcodes:

OpcodeНазваниеОписание
1HEARTBEATПоддержание соединения
2IDENTIFYАвторизация (передаётся токен)
3PRESENCE_UPDATEОбновление статуса
4VOICE_STATE_UPDATEПодключение к голосовому каналу
6RESUMEВосстановление сессии
8REQUEST_GUILD_MEMBERSЗапрос списка участников

Пример IDENTIFY:

JSON
{
  "op": 2,
  "d": {
    "token": "Bot ВАШ_ТОКЕН",
    "intents": 513,
    "properties": {
      "os": "linux",
      "browser": "discord.js",
      "device": "discord.js"
    }
  }
}

Маппинг сущностей

BANNGRU автоматически преобразует свои сущности в формат Discord API:

BANNGRUAPI форматПримечание
Сервер (servers)GuildПолный маппинг полей
Канал textGUILD_TEXT (type 0)
Канал voiceGUILD_VOICE (type 2)
Канал categoryGUILD_CATEGORY (type 4)
Участник (server_members)GuildMemberС ролями и никнеймом
Сообщение (messages)MessageВключая embeds, components
Бот (bots)User (bot=true)discriminator всегда "0000"
Роль (roles)RoleС permissions

Сообщения

Отправка сообщения (discord.js):

JavaScript
// Через 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] });

Редактирование сообщения:

JavaScript
const message = await channel.messages.fetch('message_id');
await message.edit('Обновлённый текст');

Удаление сообщения:

JavaScript
await message.delete();

Slash-команды

BANNGRU поддерживает регистрацию и обработку slash-команд через Bot API.

Регистрация команд (discord.js):

JavaScript
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-команд:

JavaScript
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БитСобытия
GUILDS1 << 0GUILD_CREATE, CHANNEL_CREATE и т.д.
GUILD_MEMBERS1 << 1GUILD_MEMBER_ADD/UPDATE/REMOVE (privileged)
GUILD_MODERATION1 << 2GUILD_BAN_ADD/REMOVE
GUILD_VOICE_STATES1 << 7VOICE_STATE_UPDATE
GUILD_PRESENCES1 << 8PRESENCE_UPDATE (privileged)
GUILD_MESSAGES1 << 9MESSAGE_CREATE/UPDATE/DELETE
GUILD_MESSAGE_REACTIONS1 << 10MESSAGE_REACTION_*
GUILD_MESSAGE_TYPING1 << 11TYPING_START
DIRECT_MESSAGES1 << 12MESSAGE_* в DM
MESSAGE_CONTENT1 << 15Доступ к content сообщений (privileged)

Пример использования:

JavaScript
const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,           // GUILD_CREATE и т.д.
    GatewayIntentBits.GuildMessages,     // MESSAGE_CREATE в каналах
    GatewayIntentBits.MessageContent,    // content, embeds, attachments
  ],
});

Rate Limits

BANNGRU имеет более строгие лимиты по сравнению со стандартным Discord API:

ЭндпоинтDiscordBANNGRU
Глобальный лимит50 req/sec25 req/sec
POST messages (на канал)5 / 5 сек3 / 5 сек
DELETE messages (на канал)5 / 1 сек3 / 2 сек
PATCH messages (на канал)5 / 5 сек3 / 5 сек
PUT reactions1 / 0.25 сек1 / 1 сек
Typing5 / 5 сек2 / 5 сек
GET members10 / 10 сек5 / 10 сек
PUT commands (bulk)2 / мин1 / мин
Gateway events120 / мин60 / мин
Gateway IDENTIFY1 / 5 сек1 / 10 сек

При превышении лимита REST API возвращает 429 Too Many Requests с заголовками:

HTTP Headers
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:

Bash
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"}'

Верификация запросов:

JavaScript
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):

JavaScript
const { joinVoiceChannel } = require('@discordjs/voice');

const connection = joinVoiceChannel({
  channelId: voiceChannel.id,
  guildId: voiceChannel.guild.id,
  adapterCreator: voiceChannel.guild.voiceAdapterCreator,
});

console.log('Подключён к голосовому каналу!');

Отключение от голосового канала:

JavaScript
connection.destroy();
console.log('Отключён от голосового канала');
Важно!
BANNGRU использует mediasoup для голосовых каналов. Полноценный голосовой протокол (UDP, Opus) работает через BANNGRU mediasoup, а не через стандартный Discord voice protocol.

Личные сообщения

Отправка DM пользователю (discord.js):

JavaScript
// Получить пользователя
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 от пользователей:

JavaScript
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:

JavaScript
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);

Запуск:

Bash
BOT_TOKEN=ваш_токен BOT_ID=10 node bot.js

Отладка

Проверка подключения:

Bash
# Проверить 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
Username3-80 символов (латиница/цифры/_)
Display name1-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 — это обеспечит максимальную совместимость и упростит миграцию между платформами.