Warum der Twitch-Bot die Nachrichten von Moderatoren überspringt

Bestimmen Sie zuerst, an welcher Stelle die Nachricht verloren geht

Prüfen Sie, ob der Bot normale Nachrichten im selben Kanal empfängt. Wenn im Log weder Zuschauer noch Moderatoren auftauchen, liegt das Problem meist an der Autorisierung, der Chat-Verbindung oder am Kanalnamen. Wenn Zuschauer sichtbar sind, die Beiträge des Moderators aber fehlen, suchen Sie die Ursache im Rollenfilter, in den IRC-Tags oder im EventSub-Abo.

Achten Sie nicht nur auf die Antwort des Bots im Chat, sondern auf das Protokoll der eingehenden Ereignisse. Die Nachricht kann die Anwendung erreichen, aber den Befehl nicht auslösen – wegen eines Präfixes, eines Cooldowns, von Stoppwörtern, einer Ignorierliste oder einer Rechteprüfung. Senden Sie zum Test dieselbe kurze Phrase und anschließend denselben Befehl sowohl von einem Zuschauer als auch von einem Moderator.

Prüfen Sie den Kanal, das Bot-Konto und die IRC-Verbindung

Stellen Sie sicher, dass der Bot genau dem richtigen Kanal und unter dem Konto beigetreten ist, das den Chat lesen soll. Nach einer Umbenennung des Kanals, einem Login-Wechsel oder dem Wechsel zwischen Test- und Produktivumgebung kann die Anwendung online bleiben, aber einen anderen Chat abhören.

Im Verbindungslog sollten die erfolgreiche Autorisierung, der Bot-Nick und der Befehl zum Betreten des Kanals sichtbar sein. Prüfen Sie nach einem Verbindungsabbruch nicht nur die Wiederverbindungsversuche, sondern auch den tatsächlichen neuen erfolgreichen Login. Eine automatische Wiederverbindung ohne Fehlerprotokollierung verdeckt ein abgelaufenes Token, ein falsches OAuth-Passwort oder einen Fehler im Kanalnamen.

Prüfen Sie das OAuth-Token und die Leserechte

Das Token muss zu dem Konto gehören, über das der Bot den Chat liest. Verwechseln Sie es nicht mit dem Token des Streamers: Die Rechte des Kanalinhabers werden nicht an ein separates Bot-Konto übertragen. Zum Lesen von Nachrichten über IRC wird der Scope chat:read benötigt.

Wenn Nachrichten über EventSub empfangen werden, wird für das Chat-Ereignis ein Benutzer-Token mit dem Recht user:read:chat benötigt. Je nach Autorisierungsschema und danach, wer das Abo erstellt, können außerdem Rechte für den Zugriff des Bots auf den Kanal erforderlich sein, einschließlich channel:bot. Fügen Sie Scopes nicht auf gut Glück hinzu: Gleichen Sie sie mit dem aktuellen Abo-Schema und dem Konto ab, in dessen Namen es erstellt wird.

Die Gültigkeit des Benutzer-Tokens und die Liste der erteilten Rechte können Sie mit folgender Anfrage prüfen:

curl -H "Authorization: OAuth $BOT_OAUTH_TOKEN" https://id.twitch.tv/oauth2/validate

Prüfen Sie in der Antwort den Login, die Benutzer-ID, die Gültigkeitsdauer und das scopes-Array. Wenn chat:read oder user:read:chat fehlt, ist eine erneute Autorisierung mit dem erforderlichen Rechtssatz nötig. Der Nachteil dieser Lösung besteht darin, dass alte Tokens und gespeicherte Sitzungen in der Bot-Konfiguration ersetzt werden müssen, sonst arbeitet der Bot weiter mit den bisherigen Rechten.

Trennen Sie die Diagnose von IRC und EventSub

IRC und EventSub liefern Nachrichten über verschiedene Wege. IRC überträgt den Chat-Stream über eine dauerhafte Verbindung: Im Rohlog muss die Zeile PRIVMSG des Moderators gefunden werden. EventSub überträgt das Ereignis channel.chat.message über ein erstelltes API-Abo: Hier prüft man dessen Status, condition und den Transport der Zustellung.

Wenn der Bot beide Quellen nutzt, protokollieren Sie die Quelle jedes Ereignisses im Log. Sonst kann eine Nachricht doppelt verarbeitet werden, und ein Ausfall eines Transports bleibt unbemerkt. Wenn nur EventSub verwendet wird, gilt das Fehlen einer IRC-Verbindung nicht als Fehler. Der Nachteil des EventSub-Schemas: Bei einem falschen oder deaktivierten Abo sieht der Bot die Nachrichten gar nicht, selbst bei funktionierendem Token.

Prüfen Sie das EventSub-Abo für Chat-Nachrichten

Suchen Sie in der Liste der Abos das Ereignis channel.chat.message. Der Eintrag muss einen aktiven Status haben. Prüfen Sie in der condition die broadcaster_user_id – das ist die ID des Streamer-Kanals – und die user_id des Benutzers, der die Ereignisse empfängt. Ein Fehler in einer dieser IDs äußert sich oft als selektives Fehlen von Nachrichten.

Rufen Sie die Liste der Abos über GET /helix/eventsub/subscriptions ab. Prüfen Sie in der Antwort type, status, condition und transport. Der Status enabled bedeutet, dass das Abo aktiv ist; Hinweise auf Zustellungsfehler, ein gelöschter Eintrag oder ein anderer Kanal weisen auf die Ursache hin. Verwenden Sie für diese Anfrage das Token und die Client ID der Anwendung, die das Abo erstellt hat.

Verlassen Sie sich nicht nur auf das Vorhandensein eines Eintrags im Panel oder in der Bot-Datenbank. Das Abo könnte für einen Testkanal erstellt, nach einem Zustellungsfehler gelöscht worden sein oder zu einer anderen Anwendung gehören. Der Nachteil der Prüfung über die API besteht darin, dass sie die Konfiguration des Abos zeigt, aber nicht die Filterlogik im Handler selbst erklärt.

Aktivieren Sie IRC-Tags und prüfen Sie die Rolle des Autors

Wenn die Rechteprüfung auf IRC basiert, muss der Client die Capability twitch.tv/tags anfordern. Ohne Tags kann der Bot den Text und den Nick des Autors erhalten, aber die Felder mod und badges nicht sehen. In diesem Fall kommen normale Befehle an, während die Moderator-Regeln fälschlich ablehnen.

Suchen Sie in der Roh-Nachricht des Moderators nach mod=1 und badges=moderator/1. Das Feld user-type kann fehlen, leer sein oder nicht der aktuellen Rolle entsprechen; verwenden Sie es daher nicht als einziges Merkmal. Der Parser muss leere Tag-Werte und escapte Zeichen korrekt verarbeiten; der Nachteil des IRC-Ansatzes liegt genau darin, dieses Format selbst auswerten zu müssen.

Wenn mod=1 fehlt, stellen Sie zuerst sicher, dass die Capability für Tags tatsächlich vom Server bestätigt und nicht nur vom Client gesendet wurde. Prüfen Sie dann badges. Der Wert moderator/1 bedeutet Moderator, broadcaster/1 – Kanalinhaber. Ein VIP hat normalerweise das Badge vip/1, aber ein VIP wird nicht automatisch Moderator. Streamer und VIP sollten nicht anhand von Nick, Farbe oder display-name als Moderatoren gelten: Bestimmen Sie die Rolle anhand von badges und separaten Zugriffsregeln.

Prüfen Sie die Rollenregeln im Code und in den Einstellungen

Vergleichen Sie die Roh-Ereignisse von Zuschauer, VIP, Moderator und Kanalinhaber mit identischem Text. Wenn das Ereignis des Moderators die Anwendung erreicht hat, der Handler es aber übersprungen hat, liegt der Fehler nach dem Empfang: in der Rollenprüfung, der Blacklist, dem Antispam oder der Befehlsweiterleitung.

• Vereinheitlichen Sie die Schreibweise der Logins vor dem Vergleich.
• Prüfen Sie mod=1 und das Badge moderator, nicht nur einen festen Satz von Tags.
• Definieren Sie die Rechte für broadcaster, moderator, vip und das Bot-Konto selbst getrennt.
• Prüfen Sie, ob der Moderator in der Ignorierliste, der Bannliste oder der Liste gesperrter Benutzer gelandet ist.
• Sehen Sie sich die Reihenfolge der Bedingungen an: Antispam oder Stoppwörter können vor der Rollenprüfung greifen.
• Stellen Sie sicher, dass der Befehl nicht durch eine Regel für Nachrichten mit Erwähnung, Link oder Textwiederholung blockiert wird.

Eine manuelle Liste von Nicks eignet sich nur für eine kurze Diagnose. Ihr Nachteil: Sie veraltet nach einem Wechsel der Moderatoren, einer Umbenennung des Kontos oder einer Änderung der Rollen im Kanal.

Schließen Sie Befehlsformat, Limits und verstecktes Ignorieren aus

Der Bot kann die Nachricht sehen und absichtlich nicht antworten. Prüfen Sie den Cooldown des Befehls, das Nachrichtenlimit pro Benutzer, den Schutz vor Wiederholungen, den Emoji-Filter und die Stoppwörter. Moderatoren senden Befehle oft schnell und können genauso wie Zuschauer vom Antispam erfasst werden.

Testen Sie separat eine normale Phrase und einen Befehl mit Präfix. Wenn die Phrase im Log steht, der Befehl aber nicht bis zum Ergebnis der Verarbeitung gelangt, prüfen Sie Präfix, Tastaturbelegung, Leerzeichen, unsichtbare Zeichen und Argumente. Befehle mit Schrägstrich und Moderationsaktionen kommen nicht immer als normaler Text an, den der Handler erwartet.

Protokollieren Sie den Entscheidungsgrund für jede Nachricht

Speichern Sie für die Diagnose Zeit, Ereignisquelle, Kanal, ID des Autors, Nachrichtentyp, Tags und Verarbeitungsergebnis. Der Text kann maskiert werden, wenn er für die Fehlersuche nicht benötigt wird. Im Log sollte ein konkreter Grund stehen: Nachricht nicht empfangen, Rolle nicht erkannt, Präfix nicht erfüllt, Cooldown ausgelöst, Benutzer ignoriert oder EventSub-Abo deaktiviert.

Schreiben Sie keine OAuth-Tokens, Anwendungsgeheimnisse, Webhook-Adressen und vollständigen Autorisierungs-Header in normale Logs. Diese Daten sind beim Debuggen nützlich, aber ihr Abfluss kann den Zugriff auf den Bot und die Anwendungseinstellungen öffnen.

Checkliste zur Diagnose in der richtigen Reihenfolge

1. Senden Sie dieselbe Phrase und denselben Befehl von einem Zuschauer und einem Moderator.
2. Prüfen Sie das Rohlog und stellen Sie fest, ob die Nachricht über IRC, EventSub oder beide Quellen kam.
3. Wenn IRC keine Nachrichten empfängt, gleichen Sie Bot-Konto, Kanalnamen, Token und den erfolgreichen Chat-Beitritt ab.
4. Wenn die IRC-Nachricht angekommen ist, stellen Sie sicher, dass Tags aktiviert sind, und prüfen Sie dann mod=1 und badges=moderator/1.
5. Wenn mod=1 fehlt, prüfen Sie die Bestätigung von twitch.tv/tags und unterscheiden Sie moderator/1, vip/1 und broadcaster/1.
6. Prüfen Sie das Token über validate: Für IRC wird chat:read benötigt, für EventSub-Nachrichten user:read:chat.
7. Prüfen Sie bei der Arbeit über EventSub channel.chat.message, den Status enabled, condition und transport in der Liste der Abos.
8. Vergleichen Sie die Rollenverarbeitung, die Ignorierliste, den Antispam, das Präfix, den Cooldown und die Stoppwörter.
9. Fügen Sie ins Log den ausdrücklichen Grund ein, aus dem jede Nachricht angenommen, ignoriert oder abgelehnt wurde.