Sibrel-Bots entwickeln

Erstelle deinen ersten Bot

• Öffne Einstellungen → Bots → Bot erstellen. Dein Host kann die Bot-Erstellung deaktivieren.
• Wähle einen Benutzernamen aus a-z0-9_, 2–32 Zeichen. Speichere das Token: Es wird nur einmal angezeigt.
• Füge den Bot in den Community-Einstellungen hinzu und vergib nur die nötigen Rechte. Verwaltung erfordert MANAGE_BOTS.
• Starte das Bot-Programm auf deinem Rechner oder Server. Ein Bot-Konto führt keinen Code aus.
• Nutze die API-Adresse des Hosts, der das Token ausgegeben hat.

Bots arbeiten in Kanälen der Communities, denen sie beigetreten sind. Die Bot-API unterstützt keine Direktnachrichten und keine öffentlichen Räume.

Authentifizierung und Geheimnisse

Authorization: Bearer <BOT_TOKEN>

Bot-Aktionen erfordern ein Bot-Token. Erstellen oder Bearbeiten eines Bots, Hinzufügen zu einer Community und Rechtevergabe erfordern das Konto-Token des Eigentümers oder Administrators. Halte diese Befugnisse getrennt.

Speichere Token in Umgebungsvariablen, nie im Browser-Code oder in Git. Die Host-Datenbank speichert Token-Hashes. Widerrufe geleakte Token und erstelle Ersatz. Das Gateway übergibt das Token in der Query-Zeichenkette, daher URLs in Reverse-Proxy- und Monitoring-Logs redigieren. Nutze HTTPS/WSS.

Minimales funktionierendes Beispiel

Erfordert Node.js 22+ mit eingebautem fetch und WebSocket. ping-bot.en.mjs herunterladen. Das Beispiel registriert /ping, antwortet in einem Kanal und verbindet sich nach einem Abbruch neu.

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

Erfolgreiches Senden: 201 { message }. Setze kein Content-Type: application/json, wenn du keinen Body sendest: Eine leere JSON-Anfrage kann 400 liefern.

Bots und Rechte verwalten

Bots haben je Community eine eigene Rechte-Bitmaske, keine normalen Mitgliedsrollen. Kanäle sehen: 16384; Nachrichten senden: 32768; Sprache: 65536. Diese drei Rechte ergeben 114688. Bots erhalten keinen Administratorzugriff.

Slash-Befehle

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

Namen: 1–32 Zeichen, a-z0-9_-. Bis zu 100 Befehle und 10 Optionen pro Befehl. Typen: string, number, boolean, user, channel, role; bis zu 25 choices. Befehlsbeschreibungen bis 200 Zeichen.

PUT ersetzt die ganze Liste, sende also immer den kompletten Satz. In message:create enthält ein erkannter Aufruf command: {bot_id, name, options, args}. Prüfe bot_id, um nicht auf Befehle eines anderen Bots zu antworten. Deaktivierte oder unbekannte Befehle kommen als normaler Text an.

Mitglied, Kanal oder Rolle auswählen

Optionen der Typen user, channel und role werden nicht von Hand getippt, sondern aus einer durchsuchbaren Liste gewählt. Der Bot erhält ein Mention-Token statt eines Namens, daher bricht das Umbenennen von Kanal, Rolle oder Mitglied nie einen bereits gesendeten Aufruf.

• Die Suche trifft den Namen und bei Mitgliedern auch Spitznamen und Login.
• Auch Dienstwörter funktionieren: „voice“ findet Sprachkanäle, „role“ findet Rollen, „text“ findet Textkanäle.
• Treffer am Namensanfang stehen über den übrigen.
• Höchstens acht Optionen werden gezeigt; verfeinere die Suche, wenn die gewünschte fehlt.
• Enter wählt die erste Option, Pfeile bewegen die Auswahl, Esc leert die Suche, Backspace kehrt zur normalen Eingabe zurück.

Der Wert kommt als Token in command.options ({ "user": "<@42>" }) und positionsgleich in command.args. Eine reine ID wird ebenfalls akzeptiert, aber nur das Token erscheint im Antworttext als Mention.

Gateway und Ereignisse

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

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

Ereignisse: message:create, message:update, message:delete, reaction:add, reaction:remove, interaction. Nutzdaten von Aktionsereignissen liegen in data; ready trägt bot_id und guilds auf oberster Ebene.

Die Verbindungswarteschlange hält 256 Nachrichten. Ein Überlauf erzeugt message:drop; ältere Ereignisse können verloren gehen. Implementiere verzögerte Neuverbindungen, Pong-Überwachung und REST-basierte Zustandswiederherstellung. Gehe nicht von Exactly-once-Zustellung aus.

Buttons, Einbettungen und Interaktionen

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

Ein Button hat ein Label bis 80 Zeichen und eine eindeutige custom_id bis 100. Link-Buttons nutzen eine http/https-URL statt custom_id. Bis zu 5 Reihen mit 5 Buttons, insgesamt 25. Stile 1–4: primary, secondary, success, danger. disabled und emoji werden unterstützt.

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

Antworte innerhalb von 3 Sekunden. ephemeral sieht nur die klickende Person; message postet in den Kanal; update bearbeitet die Nachricht mit dem Button. Ephemere Antworten bleiben bis zu 15 Minuten im Speicher und verschwinden beim Neustart; sie sind kein geheimer Speicher.

content: bis 2000 Zeichen; bis zu 10 Einbettungen mit insgesamt 6000 Zeichen. Eigene Emoji: <:name:id>. Siehe auch Webhooks für Einbettungs-Beispiele.

Sprache

POST /api/bots/voice/join liefert channel_id, identity und livekit. Ist LiveKit konfiguriert, nutze das zurückgegebene token und livekitUrl mit einem kompatiblen Client-SDK. Bei livekit: null erscheint der Bot nur in der Mitgliederliste und überträgt kein Audio. Die REST-Anfrage startet selbst keine Wiedergabe.

Fehler und Betrieb

Redigiere Geheimnisse in Logs, beschränke den Zugang zu Umgebungsvariablen und antworte nicht auf eigene Nachrichten des Bots. Stimme Datenerhebung mit Administrierenden und Nutzenden ab und definiere Aufbewahrungs- und Löschverfahren.

Sprachkanäle für Bots

Ein Bot mit dem separaten Recht CREATE_VOICE_CHANNELS kann über POST /api/bots/guilds/:guildId/channels Sprachkanäle erstellen. Statusabfrage: GET /api/bots/guilds/:guildId/voice-states. Verschieben anfordern: POST /api/bots/guilds/:guildId/voice/move. Leeren Kanal löschen: DELETE /api/bots/channels/:channelId. Der Host prüft Rechte und Grenzen; ein Token allein erteilt diese Befugnisse nicht.