Developing Sibrel bots

Create your first bot

• Open Settings → Bots → Create bot. Your host may disable bot creation.
• Choose a username using a-z0-9_, 2–32 characters. Save the token: it is shown once.
• Add the bot in community settings and grant only the permissions it needs. Management requires MANAGE_BOTS.
• Run the bot program on your computer or server. Creating a bot account does not run its code.
• Use the API address of the host that issued the token.

Bots work in channels of communities they have joined. The Bot API does not support direct messages or public spaces.

Authentication and secrets

Authorization: Bearer <BOT_TOKEN>

Bot actions require a bot token. Creating or editing a bot, adding it to a community and granting permissions require the owner’s or administrator’s account token. Keep these authorities separate.

Store tokens in environment variables, never in browser code or Git. The host database stores token hashes. Revoke leaked tokens and create replacements. Gateway passes the token in a query string, so redact URLs in reverse proxy and monitoring logs. Use HTTPS/WSS.

Minimal working example

Requires Node.js 22+ with built-in fetch and WebSocket. Download ping-bot.en.mjs. The example registers /ping, replies in a channel and reconnects after a disconnect.

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

Bot REST API

POST /api/bots/messages
{
  "channel_id": 42,
  "content": "Hello from the bot!",
  "reply_to_id": 123
}

Successful send: 201 { message }. Do not set Content-Type: application/json when sending no body: an empty JSON request may return 400.

Managing bots and permissions

Bots have a separate permission bitmask per community, not ordinary member roles. View channels: 16384; send messages: 32768; voice: 65536. These three permissions total 114688. Bots are not granted administrator access.

Slash commands

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 }
  ] }
] }

Names: 1–32 characters, a-z0-9_-. Up to 100 commands and 10 options per command. Types: string, number, boolean, user, channel, role; up to 25 choices. Command descriptions may contain up to 200 characters.

PUT replaces the whole list, so send the full set. In message:create, a recognized invocation contains command: {bot_id, name, options, args}. Check bot_id to avoid answering another bot’s commands. Disabled or unknown commands arrive as ordinary text.

Picking a member, channel or role

Options of type user, channel and role are not typed by hand — they are picked from a searchable list. The bot receives a mention token rather than a name, so renaming a channel, role or member never breaks an invocation that was already sent.

• Search matches the name and, for members, also the nickname and login.
• Service words work too: “voice” finds voice channels, “role” finds roles, “text” finds text channels.
• Matches from the start of the name rank above the rest.
• At most eight options are shown; refine the query if the one you need is missing.
• Enter picks the first option, arrows move the selection, Esc clears the search, Backspace returns to ordinary typing.

The value arrives as a token in command.options ({ "user": "<@42>" }) and as the same value positionally in command.args. A bare id is accepted too, but only the token renders as a mention in your reply text.

Gateway and events

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

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

Events: message:create, message:update, message:delete, reaction:add, reaction:remove, interaction. Action event payloads are in data; ready carries bot_id and guilds at the root.

The connection queue holds 256 messages. Overflow produces message:drop; older events may be lost. Implement delayed reconnects, pong monitoring and REST-based state recovery. Do not assume exactly-once event delivery.

Buttons, embeds and interactions

{
  "channel_id": 42,
  "embeds": [{ "title": "Test", "description": "Press the button", "color": 5793266 }],
  "components": [{ "type": 1, "components": [
    { "custom_id": "ping", "label": "Ping", "style": 1 }
  ] }]
}

A button has a label of up to 80 characters and a unique custom_id of up to 100. Link buttons use an http/https url instead of custom_id. Up to 5 rows of 5 buttons, 25 total. Styles 1–4: primary, secondary, success, danger. disabled and emoji are supported.

{ "type": "interaction-reply", "nonce": "from the event",
  "action": "ephemeral", "content": "Pong!" }

Reply within 3 seconds. ephemeral is visible to the person who clicked; message posts to the channel; update edits the message containing the button. Ephemeral replies remain in memory for up to 15 minutes and disappear on restart; they are not secret storage.

content: up to 2000 characters; up to 10 embeds with a combined limit of 6000 characters. Custom emoji: <:name:id>. See also Webhooks for embed examples.

Voice

POST /api/bots/voice/join returns channel_id, identity and livekit. When LiveKit is configured, use the returned token and livekitUrl with a compatible client SDK. With livekit: null, the bot only appears in the member list and does not transmit audio. The REST request itself does not start playback.

Errors and operation

Redact secrets in logs, restrict environment access and do not reply to the bot’s own messages. Agree on data collection with administrators and users, and define retention and deletion procedures.

Voice channels for bots

A bot with the separate CREATE_VOICE_CHANNELS permission can create voice channels using POST /api/bots/guilds/:guildId/channels. It can query states with GET /api/bots/guilds/:guildId/voice-states, request a move with POST /api/bots/guilds/:guildId/voice/move and delete an empty channel with DELETE /api/bots/channels/:channelId. The host checks permissions and limits; a token alone does not grant these actions.