Reaction Roles

Das Reaction-Roles-Modul ermöglicht es Benutzern, sich selbst Rollen zuzuweisen, indem sie mit Bot-Nachrichten interagieren — über Buttons, Dropdown-Menüs oder Emoji-Reaktionen.

Modul aktivieren

1. Dashboard → Ihr Server → Toggle Reaction Roles
2. Klicken Sie auf Edit, um Konfigurationen zu verwalten
3. Fügen Sie eine neue Konfiguration (Panel) hinzu oder bearbeiten Sie eine bestehende
4. Deployen Sie die Konfiguration auf den gewählten Kanal

Interaktionsmodi

Modus	Beschreibung
buttons	Buttons unter der Nachricht — ein Klick = Rolle umschalten
dropdown	Dropdown-Menü mit Mehrfachauswahl
reactions	Klassische Emoji-Reaktionen unter der Nachricht

Verhalten (Behavior)

Modus	Beschreibung
toggle	Klick fügt Rolle hinzu, erneuter Klick entfernt sie
add_only	Klick fügt nur die Rolle hinzu — sie kann auf diesem Weg nicht entfernt werden

Konfiguration

Jede Reaction-Roles-Konfiguration (Panel) enthält:

Option	Typ	Beschreibung
mode	string	Modus: buttons, dropdown, reactions
behavior	string	Verhalten: toggle, add_only
channel_id	string	Zielkanal
embed	object	Embed-Konfiguration (Titel, Beschreibung, Farbe)
role_mappings	array	Liste der Zuordnungen: Emoji → Rolle
max_roles	number	Max. auswählbare Rollen im Dropdown (Standard 25)
placeholder	string	Placeholder-Text im Dropdown

Struktur von role_mappings

[
  {
    "role_id": "123456789",
    "emoji": "🎮",
    "label": "Gamer"
  },
  {
    "role_id": "987654321",
    "emoji": "🎵",
    "label": "Music Lover"
  }
]

Dashboard — Konfiguration

Das Bearbeitungspanel von Reaction Roles zeigt ein Kartenraster — eine Karte pro Konfiguration:

Jede Karte enthält:

• Embed-Vorschau mit farbigen Badges
• Status: Deployed / Not deployed
• Modus (buttons/dropdown/reactions)
• Button Edit und Delete

Neue Konfiguration erstellen

1. Klicken Sie auf den Button zum Erstellen einer neuen Konfiguration
2. Füllen Sie das Embed aus (Titel, Beschreibung, Farbe)
3. Fügen Sie Rollenzuordnungen hinzu (Emoji + Rolle + Label)
4. Wählen Sie Modus und Verhalten
5. Speichern und deployen

Auto-Redeploy

Wenn Sie eine bereits deployte Konfiguration bearbeiten und speichern, bearbeitet der Bot automatisch die bestehende Nachricht auf Discord — aktualisiert Embed und Komponenten (Buttons/Dropdown). Sie müssen nicht manuell löschen und erneut deployen.

Überwachte Ereignisse

Ereignis	Aktion
on_interaction	Verarbeitung von Button-Klicks und Dropdown-Auswahlen
on_raw_reaction_add	Verarbeitung hinzugefügter Reaktionen (Modus Reactions)
on_raw_reaction_remove	Verarbeitung entfernter Reaktionen (Modus Reactions, nur Toggle)

Funktionsablauf

Modus Buttons

1. Benutzer klickt einen Button
2. Bot parst custom_id (Format: rr:{role_id})
3. Prüft, ob der Bot diese Rolle verwalten kann (Hierarchie)
4. Toggle: wenn Benutzer die Rolle hat → entfernt sie; wenn nicht → fügt sie hinzu
5. Sendet ephemerale Antwort
6. Protokolliert die Änderung im Logs-Modul

Modus Dropdown

1. Benutzer wählt Rollen aus dem Menü (kann mehrere auswählen)
2. Bot vergleicht ausgewählte Rollen mit aktuell besessenen
3. Fügt fehlende hinzu, entfernt abgewählte (im Toggle-Modus)
4. Sendet Zusammenfassung der Änderungen

Modus Reactions

1. Benutzer fügt Emoji-Reaktion hinzu
2. Bot ordnet Emoji der role_id zu
3. Fügt dem Benutzer die Rolle hinzu
4. Bei Entfernung der Reaktion (Toggle) — entfernt die Rolle

Tracking deployter Nachrichten

Deployte Nachrichten werden in der Tabelle reaction_role_messages gespeichert:

• message_id — ID der Nachricht auf Discord
• config_index — Index der Konfiguration im Array

Der Bot lädt diese Daten beim Start und hält sie im Speicher für schnelles Routing von Interaktionen.

Protokollierung

Rollenänderungen werden durch Logs unter der Kategorie reaction_roles protokolliert:

• Role Added — Rollenzuweisung (mit Info zur Methode: Button/Dropdown/Reaction)
• Role Removed — Rollenentfernung
• Error — Fehlende Rolle (Rolle wurde nach der Konfiguration vom Server gelöscht)

Fehlerbehandlung

• Fehlende Rolle — wenn eine konfigurierte Rolle nicht existiert, erhält der Benutzer eine ephemerale Nachricht "This role no longer exists. Please contact an administrator." + Fehlerlog
• Rollenhierarchie — wenn der Bot eine Rolle nicht verwalten kann, zeigt er eine Meldung an, dass die Bot-Rolle höher positioniert werden muss

Tipps

Best Practices

• Verwenden Sie den Modus Buttons für wenige Rollen (1–5) — am intuitivsten
• Verwenden Sie den Modus Dropdown für viele Rollen (6+) — nimmt weniger Platz ein
• Der Modus Reactions ist Legacy — Buttons/Dropdown sind zuverlässiger
• Setzen Sie eindeutige Emojis und Labels, damit Benutzer wissen, was sie auswählen
• Überprüfen Sie die Rollenhierarchie nach der Konfiguration — die Bot-Rolle muss höher sein als die Self-Assign-Rollen

Wichtig

Nach dem Löschen einer Rolle von Discord aktualisiert sich die Reaction-Roles-Konfiguration nicht automatisch. Entfernen Sie die nicht existierende Rolle aus der Konfiguration im Dashboard, um Fehler zu vermeiden.