Discourse AI: Discord Bot Integrationsanleitung

[DevTeVe (DevTek Ve)]

Funktionsweise (Architektur)

Bevor Sie dies einrichten, ist es wichtig zu verstehen, dass Sie keine separate Bot-Anwendung hosten oder ein „Bot“-Skript (wie einen Node.js- oder Python-Bot) auf Ihrem Server ausführen müssen.

Diese Integration verwendet Discord Interactions (Webhooks) in Kombination mit Progressiven Bearbeitungen, um ein Streaming-KI-Erlebnis zu simulieren:

1. Benutzeraktion: Ein Benutzer gibt in Ihrem Discord-Server /ask ein.
2. Webhook: Discord sendet eine HTTP POST-Anfrage direkt an Ihren Discourse-Server.
3. Sofortige Bestätigung (Ack): Discourse antwortet sofort mit dem Status „Searching…“. Dies verhindert das Timeout „Interaction Failed“ von Discord.
4. Streaming-Antwort: Ein Hintergrundauftrag beginnt mit der Generierung der KI-Antwort. Während die KI Text produziert, sendet Discourse häufig HTTP PATCH-Anfragen, um die Discord-Nachricht in Echtzeit zu bearbeiten.

Ergebnis: Benutzer sehen die Antwort live eintippen, ähnlich wie bei ChatGPT, anstatt auf einen einzigen statischen Textblock zu warten.

Hauptvorteil: Da Discourse die Logik intern verwaltet, gibt es keine zusätzliche Infrastruktur, die gewartet werden muss. Wenn Ihr Forum online ist, ist Ihr Bot online.

Diese Anleitung beschreibt den vollständigen Prozess zur Integration des Discourse AI-Bots mit einem Discord-Server. Sie enthält spezifische Anweisungen zur manuellen Registrierung von Slash-Befehlen über die API, was derzeit erforderlich ist, um automatische Synchronisierungsprobleme im Plugin zu umgehen.

Voraussetzungen

• Discourse Admin-Zugriff: Sie müssen Administrator Ihrer selbst gehosteten Discourse-Instanz sein.
• Discord Admin-Zugriff: Sie müssen über die Berechtigung „Server verwalten“ auf dem Ziel-Discord-Server verfügen.
• Terminalzugriff: Sie benötigen ein Terminal, um curl-Befehle auszuführen.

1. Erstellen der Discord-Anwendung

1. Navigieren Sie zum Discord Developer Portal.
2. Klicken Sie oben rechts auf New Application.
3. Geben Sie Ihrer Anwendung einen Namen (z. B. „Discourse Helper“) und klicken Sie auf Create.
4. Anmeldedaten kopieren: Suchen Sie auf der Seite General Information die folgenden Informationen und speichern Sie sie für später:

2. Konfigurieren des Bot-Benutzers

1. Klicken Sie im linken Seitenmenü auf Bot.

2. Klicken Sie auf Reset Token.

3. Privilegierte Intents aktivieren:

   • Scrollen Sie nach unten zum Abschnitt „Privileged Gateway Intents“.
   • Schalten Sie Message Content Intent auf ON. (Dies ermöglicht es dem Bot, die Nachrichten zu lesen, auf die er antworten muss).

4. Klicken Sie auf Save Changes.

3. Konfigurieren der Discourse-Einstellungen

1. Melden Sie sich in Ihrem Discourse Admin Panel an.

2. Navigieren Sie zu Admin → Plugins → AI → Features.

3. Suchen Sie nach „discord“ und klicken Sie auf Bearbeiten:
   

   

4. Füllen Sie die Details aus

   • AI Discord app ID: Fügen Sie =ApplicationId= ein
   • AI Discord app public key: Fügen Sie =PublicKey= ein
     
     

5. Ihren Discord-Server erlauben:

   • Öffnen Sie Ihre Discord-App und aktivieren Sie den Entwicklermodus (Benutzereinstellungen → Erweitert → Entwicklermodus).
   • Klicken Sie mit der rechten Maustaste auf Ihr Server-Symbol in der Seitenleiste und wählen Sie Server-ID kopieren.
   • Fügen Sie diese ID in den Discourse-Einstellungen in das Feld AI Discord allowed guilds ein.

4. Festlegen des Interactions-Endpunkts

1. Erstellen Sie Ihre Endpunkt-URL: https://=ForumUrl=/discourse-ai/discord/interactions
2. Kehren Sie zum Discord Developer Portal zurück.
3. Scrollen Sie auf der Seite General Information zum Interactions Endpoint URL.
4. Fügen Sie Ihre URL ein und klicken Sie auf Save Changes.
   • Erfolg: Discord sendet ein Testsignal. Wenn es ohne Fehler gespeichert wird, hat Ihre Discourse-Instanz die Signatur erfolgreich verifiziert.
   • Fehler: Wenn Sie einen Fehler erhalten, stellen Sie sicher, dass AI Discord app ID und AI Discord app public key in den Discourse-Einstellungen korrekt gespeichert sind.

5. Den Bot einladen

1. Klicken Sie im Developer Portal in der Seitenleiste auf Installation.
2. Scopes: Setzen Sie Häkchen bei bot und applications.commands.
3. Bot-Berechtigungen: Setzen Sie folgende Häkchen:
   • Nachrichten senden (Send Messages)
   • Links einbetten (Embed Links)
   • Dateien anhängen (Attach Files)
   • Nachrichtenverlauf lesen (Read Message History)
4. Kopieren Sie den Installation Link oben auf der Seite.
5. Öffnen Sie diese URL in einem Browser-Tab und autorisieren Sie den Bot, Ihrem Server beizutreten.

6. Registrieren des Slash-Befehls (Manueller API-Aufruf)

Wichtig: Der Befehlsparametername MUSS query sein.

Für Mac / Linux (Bash)

curl -X POST "https://discord.com/api/v10/applications/=ApplicationId=/commands" \
  -H "Authorization: Bot =BotToken=" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ask",
    "description": "Stelle der KI eine Frage",
    "options": [
        {
            "name": "query",
            "description": "Was ist deine Frage?",
            "type": 3,
            "required": true
        }
    ]
}'

• Erfolgreiche Antwort: Sie sollten eine JSON-Antwort erhalten, die die ID des neuen Befehls enthält.
• Fehler 401? Stellen Sie sicher, dass Sie das Wort Bot (mit einem Leerzeichen) vor Ihrem Token im Authorization-Header beibehalten haben.

7. Überprüfung

1. Öffnen Sie Ihren Discord-Server.
2. Geben Sie /ask in einem Textkanal ein.
3. Das Befehlsmenü sollte erscheinen. Wählen Sie /ask und geben Sie eine Frage in das Feld query ein.
4. Erwartetes Verhalten:
   • Sofort: Der Bot antwortet mit „Searching…“
   • Nach einigen Sekunden: Die Nachricht wird mit der Antwort der KI aktualisiert.

Fehlerbehebung

Fehler	Ursache	Lösung
401 Unauthorized (in Curl)	Falsches Token-Format	Stellen Sie sicher, dass der Header Authorization: Bot =BotToken= lautet. Verwenden Sie das Token aus dem Tab Bot, nicht aus dem Tab Allgemein.
Job Exception: context must be an instance of BotContext	Falsche Nutzlast	Stellen Sie sicher, dass Sie auf dem neuesten Stand sind. Dies wurde unter FIX: Discord Bot crash due to missing BotContext in PersonaReplier by devtekve · Pull Request #36429 · discourse/discourse · GitHub behoben.