Warum klappen einzelne Bot-Funktionen nicht? (Best Practices)

Wenn einzelne Funktionen des CitrusTools-Discord-Bots nicht greifen, liegt es fast nie am Bot selbst — sondern an Discords Rechte-System. Dieser Eintrag fasst die wichtigsten Stolperfallen zusammen.

---

Die wichtigste Regel: Rollen-Hierarchie

Der Bot kann nur Rollen vergeben oder entziehen, die in der Server-Hierarchie unter seiner eigenen Rolle stehen. Das gilt für Reaction-Roles, Sub-Sync, Geburtstags-Rollen — einfach alles.

So setzt ihrs richtig auf:

1. In Discord: Servereinstellungen → Rollen.
2. Die Rolle des CitrusTools-Bots (Standard: „CitrusTools" oder euer Custom-Bot-Name) so weit wie möglich nach oben ziehen.
3. Alle Rollen, die der Bot später vergeben soll, müssen darunter liegen.

💡 Idealerweise liegt die Bot-Rolle direkt unter eurer Admin-Rolle — höher als alle Auto-Rollen, niedriger als ihr selbst.

---

Bot-Rolle nicht löschen oder umbenennen

Discord erzeugt beim Einladen eine dedizierte „Integration"-Rolle für den Bot. Diese trägt die eigentlichen Bot-Permissions.

• Nicht löschen — die Rolle ist Discord-seitig an die Bot-Application gebunden. Ohne sie ist der Bot rechtelos und der einzige Weg zurück ist ein Re-Invite.
• Nicht stark einschränken — wer hier Häkchen wegnimmt, bricht gezielt einzelne Features.
• Umbenennen ist okay, ändert nichts an den Rechten.

---

Channel-Overrides schlagen Server-Rechte

Auch wenn der Bot serverweit alle Rechte hat: Wenn in einem einzelnen Channel ein Override gesetzt ist, der ihm das Schreiben verbietet, schweigt er dort.

Wenn ein Channel-Feature nicht läuft, prüft:

1. Channel öffnen → ⚙️ → Berechtigungen.
2. Bot-Rolle (oder @everyone-Fallback) anschauen.
3. Kanal anzeigen, Nachrichten senden, Embeds einbetten, Reaktionen hinzufügen müssen erlaubt sein.

---

Was die einzelnen Features konkret brauchen

• Welcome-Messages: Nachrichten senden + Embeds einbetten im Welcome-Channel.
• Reaction-Roles: Reaktionen hinzufügen + Rollen verwalten (server­weit) + Bot-Rolle über der vergebenen Rolle.
• Twitch-Sub-Sync: Rollen verwalten + Bot-Rolle über der Sub-Rolle. Eure Zuschauer*innen müssen ihren Discord-Account einmal im CitrusTools-Profil verknüpfen.
• Stream-Notifications: Nachrichten senden im Ziel-Channel, Embeds einbetten, Rollen erwähnen (falls ihr @LIVE pingt).
• Stats-Channel (Voice-Counter): Kanäle verwalten (zum Umbenennen) — Standard ist das nicht dabei und muss gezielt erlaubt werden.
• Auto-Reactions: Reaktionen hinzufügen im jeweiligen Channel.

---

„Bei mir kommt der Banner immer wieder" — Updates sind normal

Wenn wir dem Bot neue Funktionen geben, fragen wir gezielt zusätzliche Rechte an. Dann erscheint im Dashboard ein orangefarbener Re-Invite-Banner. Das ist kein Fehler — ein Klick auf den Server-Button reicht, dann ist Ruhe.

Mehr dazu: Discord-Bot re-inviten, wenn neue Berechtigungen nötig sind.

---

Schnell-Check, wenn etwas nicht klappt

1. Bot-Rolle über betroffener Rolle? (Hierarchie)
2. Channel-Override blockiert? (Channel-Rechte)
3. Re-Invite-Banner offen? (fehlende neue Rechte)
4. Bot-Status im Dashboard „aktiv"? (Token gültig)
5. Fehler-Anzeige im Dashboard (zeigt das letzte Problem an)

Wenn ihr nach dieser Liste noch nicht weiterkommt: schreibt uns über das Feedback-Tool oder über unseren Discord-Server, mit Server-Name und kurzer Beschreibung, was nicht funktioniert — dann schauen wir gemeinsam drauf.