Створіть першого бота
- Відкрийте Налаштування → Боти → Створити бота. Створення може бути вимкнено на хості.
- Укажіть ім’я
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.mjsREST 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 після розриву.
Голос
Бот із потрібними правами може під’єднатися до голосового каналу. Для медіа потрібен налаштований 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. Після повторного підключення отримайте актуальний стан. Хост дозволяє видалення, коли підтверджено, що канал порожній.