Разработка ботов Sibrel

Создать первого бота

• Откройте «Настройки → Боты → Создать бота». Хост может запрещать создание ботов.
• Задайте логин из a-z0-9_, 2–32 символа. Сохраните токен: он показывается один раз.
• В настройках сообщества добавьте бота и выдайте только необходимые права. Для управления требуется MANAGE_BOTS.
• Запустите программу бота на своей машине или сервере. Наличие аккаунта бота само по себе не запускает его код.
• Укажите адрес API именно того хоста, который выдал токен.

Боты работают в каналах сообществ, куда добавлены. Личные сообщения и паблики через Bot API недоступны.

Авторизация и секреты

Authorization: Bearer <BOT_TOKEN>

Для действий бота нужен его токен. Создание и редактирование бота, добавление в сообщество и выдача прав выполняются с токеном аккаунта владельца или администратора. Не смешивайте эти полномочия.

Храните токены в переменных окружения, не в браузерном коде и не в Git. В базе хоста хранится хеш токена. При утечке отзовите старый токен и создайте новый. Gateway передаёт токен в query string, поэтому настройте очистку URL в журналах reverse proxy и мониторинга. Используйте HTTPS/WSS.

Минимальный работающий пример

Нужен Node.js 22+ со встроенными fetch и WebSocket. Скачать ping-bot.mjs. Пример регистрирует /ping, отвечает в канале и повторно подключается после разрыва связи.

$env:SIBREL_API_URL = "https://api.example.org"
$env:SIBREL_BOT_TOKEN = "ваш-токен"
node ./ping-bot.mjs

REST API бота

POST /api/bots/messages
{
  "channel_id": 42,
  "content": "Привет от бота!",
  "reply_to_id": 123
}

Успех отправки: 201 { message }. Без тела запроса не ставьте Content-Type: application/json: пустой JSON-запрос может вернуть 400.

Управление ботом и правами

У бота отдельная маска прав на каждом сообществе, а не обычные роли участника. Просмотр каналов — 16384, отправка сообщений — 32768, голос — 65536. Сумма этих трёх прав — 114688. Доступ администратора боту не выдаётся.

Слеш-команды

PUT /api/bots/commands
{ "commands": [
  { "name": "ping", "description": "Проверить ответ бота", "options": [] },
  { "name": "echo", "description": "Повторить текст", "options": [
    { "name": "text", "description": "Ваш текст", "type": "string", "required": true }
  ] }
] }

Имя: 1–32 символа, a-z0-9_-. До 100 команд, до 10 параметров у команды; типы string, number, boolean, user, channel, role, до 25 вариантов choices. Описание команды — до 200 символов.

PUT заменяет весь список, поэтому отправляйте полный набор. В message:create распознанный вызов содержит command: {bot_id, name, options, args}. Проверяйте bot_id, чтобы не отвечать на команды другого бота. Отключённая или неизвестная команда приходит обычным текстом.

Выбор участника, канала и роли

Параметры типов user, channel и role человек не печатает руками — он выбирает их из списка с поиском. Боту уходит токен упоминания, а не название, поэтому переименование канала, роли или участника не ломает уже отправленный вызов.

• Поиск идёт по названию, а у участника — ещё по нику и логину.
• Служебные слова тоже работают: «голос» находит голосовые каналы, «роль» — роли, «текст» — текстовые.
• Совпадения с начала названия идут выше остальных.
• Показывается до восьми вариантов; если нужного не видно, уточните запрос.
• Enter выбирает первый вариант, стрелки двигают выделение, Esc очищает поиск, Backspace возвращает к обычному вводу.

В поле command.options приходит токен ({ "user": "<@42>" }), а в command.args — то же значение позиционным аргументом. Голый id бот тоже может принять, но в тексте ответа токен читается как обычное упоминание, а просто число — нет.

Gateway и события

wss://api.example.org/api/bots/gateway?token=<BOT_TOKEN>

{ "type": "ready", "bot_id": 7, "guilds": [1, 2] }
{ "type": "ping" }
{ "type": "pong" }

События: message:create, message:update, message:delete, reaction:add, reaction:remove, interaction. Содержимое событий действий находится в data; ready передаёт bot_id и guilds в корне.

Очередь соединения ограничена 256 сообщениями. При переполнении приходят message:drop; старые события могут быть потеряны. Добавьте переподключение с задержкой, контроль pong и восстановление нужного состояния через REST. Не обещайте однократное получение каждого события.

Кнопки, embeds и interactions

{
  "channel_id": 42,
  "embeds": [{ "title": "Проверка", "description": "Нажмите кнопку", "color": 5793266 }],
  "components": [{ "type": 1, "components": [
    { "custom_id": "ping", "label": "Пинг", "style": 1 }
  ] }]
}

Кнопка имеет label до 80 символов и уникальный custom_id до 100. Для ссылки используется url http/https вместо custom_id. До 5 рядов по 5 кнопок, максимум 25. Styles 1–4: primary, secondary, success, danger. Допустимы disabled и emoji.

{ "type": "interaction-reply", "nonce": "из события",
  "action": "ephemeral", "content": "Понг!" }

Ответьте в течение 3 секунд. ephemeral виден кликнувшему, message отправляет сообщение в канал, update изменяет сообщение с кнопкой. Ephemeral хранится в памяти до 15 минут и исчезает при перезапуске; это не механизм хранения секретов.

Текст content — до 2000 символов; до 10 embeds с общим лимитом 6000 символов. Кастомный emoji: <:name:id>. Формат карточек также описан в справке по вебхукам.

Голос

После POST /api/bots/voice/join ответ содержит channel_id, identity и livekit. При настроенном LiveKit используйте возвращённые token и livekitUrl с совместимым клиентским SDK. При livekit: null бот только присутствует в списке, но не передаёт звук. Сам REST-запрос не начинает воспроизведение аудио.

Ошибки и эксплуатация

Скрывайте секреты в логах, ограничивайте доступ к окружению, не отвечайте на сообщения самого бота. Согласуйте сбор данных с администратором и пользователями, определите срок хранения и способ удаления.

Голосовые каналы для ботов

Бот с отдельным правом CREATE_VOICE_CHANNELS может создавать голосовые каналы через POST /api/bots/guilds/:guildId/channels. Доступны запрос состояний через GET /api/bots/guilds/:guildId/voice-states, запрос перемещения через POST /api/bots/guilds/:guildId/voice/move и удаление пустого канала через DELETE /api/bots/channels/:channelId. Права и ограничения проверяются хостом; наличие токена само по себе не даёт эти полномочия.