Bots und Webhooks für Lobus.

Überblick

Lobus bietet zwei Wege, Dinge zu automatisieren. Es gibt außerdem ein kleines Bot-SDK für Node.js.

Schnellstart: Webhook in zwei Minuten

1. In den Server-Einstellungen den Tab Apps öffnen und einen Webhook für den gewünschten Kanal anlegen (Name vergeben).
2. Die geheime Adresse wird nur einmal angezeigt. Sie hat die Form https://<deine-lobus-adresse>/api/v1/hooks/<webhook-id>/<geheimer-teil>. Behandle sie wie ein Passwort.
3. Nachricht senden:

curl -X POST "https://<deine-lobus-adresse>/api/v1/hooks/<webhook-id>/<geheimer-teil>" \
  -H "content-type: application/json" \
  -d '{"content":"Build #42 ist durch ✅"}'

Antwort bei Erfolg: 204 No Content.

Regeln für Webhooks

• Body (JSON, nur diese Felder): content (Text, bis 4000 Zeichen) und optional embeds (bis 10 Stück).
• Der Absendername ist fest der Webhook-Name; er kann nicht pro Nachricht geändert werden.
• Höchstens 10 Webhooks pro Server.
• Wer die URL kennt, kann in genau diesen einen Kanal schreiben. Wurde sie verraten: Webhook löschen und neu anlegen.
• Höchstens 120 Aufrufe pro Minute und IP-Adresse (danach 429 mit Wartezeit).

Embeds (strukturierte Nachrichten)

Embeds enthalten nur Text und sind für Bots und Webhooks erlaubt. Keine Bilder oder Links von außen.

{
  "content": "",
  "embeds": [
    {
      "title": "Deployment",
      "description": "Version 1.4.2 ist live.",
      "color": "#7c5cff",
      "fields": [
        { "name": "Dauer", "value": "42 s", "inline": true },
        { "name": "Branch", "value": "main", "inline": true }
      ],
      "footer": "CI"
    }
  ]
}

Grenzen: höchstens 3 Embeds je Bot-Nachricht, Titel 256 Zeichen, Beschreibung 2000, bis zu 10 Felder, Fußzeile 128, insgesamt 4000 Zeichen.

Bots

Bot anlegen und einsetzen

1. Einstellungen → Dev-Portal (Bots) öffnen und eine Anwendung anlegen.
2. Das Token (lobus_bot_…) wird nur einmal angezeigt. Der Server speichert nur einen SHA-256-Hash. Bei Verlust: „Token neu“.
3. Im Dev-Portal den Bot in einen Server einsetzen. Dafür brauchst du dort das Recht „Rollen verwalten“. Der Bot bekommt nie mehr Rechte als du; das Administrator-Recht kann nur der Server-Inhaber vergeben.
4. Token nur als Umgebungsvariable an den Bot-Prozess geben, nie in Code, Git oder Chat.

Bots sind normale Mitglieder mit einer verwalteten Rolle. Sie sehen nur Kanäle, die ihre Rolle erlaubt, und werden wie Nutzer berechtigt und ratenbegrenzt. Token zurücksetzen, löschen und einsetzen steht im Protokoll.

Anmeldung

Jede Anfrage trägt den Header Authorization: Bot <token>.

Bots dürfen: Server lesen, Kanalnachrichten lesen, senden, bearbeiten und löschen, Reaktionen, Dateien, ein Gateway-Ticket holen, Mitglieder entfernen, sperren und mit Timeout belegen, Rollen vergeben und eigene Slash-Befehle melden. Alles andere (Freunde, Direktnachrichten, Profil, Dev-Portal, Server-Verwaltung) ist Menschen vorbehalten.

Nachrichten senden

POST /api/v1/channels/:channelId/messages
{ "content": "…", "embeds": [ … ] }

Echtzeit-Ereignisse (Gateway)

1. Ticket holen: POST /api/v1/gateway/ticket (gültig 30 Sekunden, einmal verwendbar).
2. WebSocket öffnen: wss://<deine-lobus-adresse>/gateway?ticket=<ticket>.
3. Ereignisse kommen als JSON { "t": "<Typ>", "d": { … } }. Wichtige Typen: ready, message.create, message.update, message.delete, interaction.create, presence.update.

POST /api/v1/gateway/ticket
wss://<deine-lobus-adresse>/gateway?ticket=<ticket>
{ "t": "message.create", "d": { … } }

Das SDK kümmert sich um Ticket, Verbindung und automatisches Neuverbinden mit Wartezeit.

Slash-Befehle

• Der Bot meldet seine Befehle mit PUT /api/v1/bot/commands (ersetzt alle bisherigen, höchstens 50). Namen: a-z, 0-9, _, -. Optionen haben den Typ string, integer oder boolean.
• Nutzer tippen / und sehen Vorschläge, dann /befehl wert ….
• Der Bot erhält im Gateway interaction.create mit einem einmaligen token.
• Antwort: POST /api/v1/interactions/:id/:token/callback mit { "content": "…", "embeds": [ … ] }. Gültig 15 Minuten, höchstens 5 Antworten. Dafür ist kein Bot-Header nötig, nur das Token aus dem Ereignis.

[
  {
    "name": "wuerfeln",
    "description": "Würfelt eine Zahl",
    "options": [
      { "name": "seiten", "description": "Anzahl Seiten", "type": "integer", "required": true }
    ]
  }
]

POST /api/v1/interactions/:id/:token/callback
{ "content": "…", "embeds": [ … ] }

Bot-SDK (Node.js)

Ohne Abhängigkeiten, Node 22 oder neuer (eingebautes fetch und WebSocket). Das SDK liegt im Lobus-Projekt unter packages/bot-sdk. Eine Veröffentlichung als Paket gibt es noch nicht.

import { Bot } from './packages/bot-sdk/src/index.ts';

const bot = new Bot({
  baseUrl: process.env.LOBUS_URL ?? '',
  token: process.env.LOBUS_BOT_TOKEN ?? '',
});

bot.on('ready', async () => {
  await bot.rest.setCommands([
    {
      name: 'wuerfeln',
      description: 'Würfelt eine Zahl',
      options: [{ name: 'seiten', description: 'Anzahl Seiten', type: 'integer', required: true }],
    },
  ]);
});

bot.on('interaction.create', async (i) => {
  if (i.command !== 'wuerfeln') return;
  const seiten = Math.min(Math.max(Number(i.options.seiten) || 6, 2), 1000);
  const wurf = 1 + Math.floor(Math.random() * seiten);
  await bot.rest.respond(i, '', [
    { title: 'Wurf', description: `${i.user.displayName} würfelt eine ${wurf} (W${seiten})`, color: '#7c5cff' },
  ]);
});

await bot.start();

Start:

LOBUS_URL=https://<deine-lobus-adresse> LOBUS_BOT_TOKEN=lobus_bot_… node bot.ts

Das SDK sendet das Token nur an die angegebene Adresse, hält es nur im Speicher und fängt Fehler einzelner Handler ab, ohne den Bot zu beenden.

Fehler

Fehler kommen als JSON { "error": "<code>" } mit passendem HTTP-Status:

Sicherheit auf einen Blick

• Tokens und Webhook-URLs sind Geheimnisse: nie in Code, Repositories oder Chats.
• Bot-Token liegen serverseitig nur als Hash.
• Bots haben nie mehr Rechte als die Person, die sie eingesetzt hat.
• Einmalige Interaktions- und Gateway-Tokens laufen schnell ab.

Noch nicht vorhanden