Для розробників

Розробка ботів для Sibrel

Токени, права, REST API, Gateway, команди, кнопки та приклад Node.js.

Звірено з проєктом: 2026-11-18 · Підтримка: support@sibrel.net

Створіть першого бота

  • Відкрийте Налаштування → Боти → Створити бота. Створення може бути вимкнено на хості.
  • Укажіть ім’я a-z0-9_ довжиною 2–32 символи. Збережіть показаний один раз токен.
  • Додайте бота в налаштуваннях спільноти та надайте потрібні права. Для керування потрібне MANAGE_BOTS.
  • Запустіть код бота й використовуйте API хоста, який видав токен.

Bot API працює в каналах спільнот, до яких додано бота.

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

Authorization: Bearer <BOT_TOKEN>

Токен бота потрібен для дій бота. Керування ботом і його правами потребує токена користувача з відповідними повноваженнями. Зберігайте секрети у змінних середовища. Використовуйте HTTPS/WSS і вилучайте токени Gateway з журналів URL.

Мінімальний приклад

Потрібен Node.js 22+ з fetch і WebSocket. Завантажити ping-bot.en.mjs. Приклад реєструє /ping, відповідає та відновлює з’єднання.

$env:SIBREL_API_URL = "https://api.example.org"
$env:SIBREL_BOT_TOKEN = "your-token"
node ./ping-bot.en.mjs

REST API бота

Метод і шляхДія
GET /api/bots/meПрофіль, команди та спільноти.
GET /api/bots/guildsСпільноти бота.
GET /api/bots/guilds/:guildId/channelsДоступні канали.
GET /api/bots/channels/:channelId/messages?limit=20&before=:idІсторія з лімітом до 100.
POST /api/bots/messagesНадіслати content, embeds або components у channel_id.
PATCH /api/bots/messages/:idЗмінити повідомлення бота.
DELETE /api/bots/messages/:idВидалити повідомлення. mode=hard потребує прав.
POST /api/bots/channels/:id/typingПоказати введення, відповідь 204.
GET /api/bots/commandsСписок команд.
PUT /api/bots/commandsЗамінити глобальні команди.
PUT /api/bots/guilds/:guildId/commandsЗамінити команди спільноти.
POST /api/bots/voice/joinПід’єднатися з параметром channel_id.
POST /api/bots/voice/leaveВийти з каналу, відповідь 204.
POST /api/bots/messages
{
  "channel_id": 42,
  "content": "Hello from the bot!",
  "reply_to_id": 123
}

Успішне надсилання повертає 201 { message }. Для запитів без тіла не задавайте Content-Type: application/json.

Керування ботами та правами

Метод і шляхДія
GET /api/bots; POST /api/botsСписок і створення бота.
PATCH /api/bots/:id; DELETE /api/bots/:idРедагування або видалення.
GET /api/bots/:id/tokens; POST /api/bots/:id/tokensСписок і видача токена.
DELETE /api/bots/:id/tokens/:tokenIdВідкликати токен.
POST /api/guilds/:guildId/botsДодати бота за bot_id.
DELETE /api/guilds/:guildId/bots/:botIdВилучити бота зі спільноти.
GET /api/guilds/:guildId/bots/:botId/permissionsПоточні та доступні права.
PUT /api/guilds/:guildId/bots/:botId/permissionsЗаписати бітову маску як рядок.

Перегляд каналів: 16384; надсилання: 32768; голос: 65536. Разом ці права дають маску 114688.

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

PUT /api/bots/commands
{ "commands": [
  { "name": "ping", "description": "Check the bot response", "options": [] },
  { "name": "echo", "description": "Repeat text", "options": [
    { "name": "text", "description": "Your text", "type": "string", "required": true }
  ] }
] }

Імена: a-z0-9_-, 1–32 символи. До 100 команд і 10 параметрів на команду, до 25 варіантів choices. PUT замінює весь список. У message:create перевіряйте command.bot_id перед відповіддю.

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

ТипЗначення
user<@id>
channel<#id>
role<@&id>

Пошук показує доступні об’єкти поточної спільноти. Enter вибирає перший результат, стрілки переміщують вибір. Бот отримує токен у command.options та command.args.

Gateway і події

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

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

Gateway передає message:create, message:update, message:delete, reaction:add, reaction:remove й interaction. Дані дії містяться в data. Черга має до 256 подій. За переповнення message:drop повідомляє про втрату. Відновлюйте стан через REST після розриву.

Кнопки, картки та взаємодії

{
  "channel_id": 42,
  "embeds": [{ "title": "Test", "description": "Press the button", "color": 5793266 }],
  "components": [{ "type": 1, "components": [
    { "custom_id": "ping", "label": "Ping", "style": 1 }
  ] }]
}
{ "type": "interaction-reply", "nonce": "from the event",
  "action": "ephemeral", "content": "Pong!" }

Пов’язуйте кнопку з custom_id і перевіряйте права користувача перед дією. Для простих повідомлень з інших сервісів доступні вебхуки.

Голос

Бот із потрібними правами може під’єднатися до голосового каналу. Для медіа потрібен налаштований LiveKit. Використовуйте токен кімнати, виданий API, і обробляйте розриви підключення.

Помилки й експлуатація

  • 401: перевірте токен і API хоста.
  • 403: перевірте права й доступ до каналу.
  • 429: дотримуйтеся Retry-After.
  • За розриву Gateway виконуйте повторне підключення із затримкою.

Голосові канали для ботів

Бот може керувати голосовими кімнатами спільноти через Bot API. Він має бути учасником спільноти й мати права VIEW_CHANNELS та SEND_VOICE. Створення, видалення й переміщення учасників потребують окремих прав.

ДіяЗапитДодаткове право
Створити голосовий каналPOST
/api/bots/guilds/:guildId/channels
CREATE_VOICE_CHANNELS
Отримати голосові станиGET
/api/bots/guilds/:guildId/voice-states
—
Запросити переміщення учасникаPOST
/api/bots/guilds/:guildId/voice/move
MOVE_VOICE_MEMBERS
Видалити порожній каналDELETE
/api/bots/channels/:channelId?only_if_empty=true
DELETE_VOICE_CHANNELS

Створення кімнати

POST /api/bots/guilds/:guildId/channels

{
  "name": "Кімната команди",
  "category_id": 10,
  "user_limit": 5
}

Запит на переміщення

POST /api/bots/guilds/:guildId/voice/move

{
  "user_id": 3,
  "channel_id": 5
}

Події voice:join, voice:leave і voice:move надходять через /api/bots/gateway. Після повторного підключення отримайте актуальний стан. Хост дозволяє видалення, коли підтверджено, що канал порожній.