Twitch Setup Chatlix mit Twitch verbinden, Permissions, Webhooks. Twitch verbinden Twitch verbinden Um Twitch-Events (Subs, Bits, Rewards, Follower, Chat) in Chatlix zu nutzen, musst du deinen Twitch-Account einmalig verbinden. Das passiert über OAuth — du wirst auf twitch.tv weitergeleitet, bestätigst dort die Zugriffsrechte, und kommst zurück ins Dashboard. Voraussetzungen Aktiver Chatlix-Account mit Streamer-Rolle. Twitch-Account (ein Affiliate- oder Partner-Status ist nicht zwingend, aber einige Features wie Subs / Bits funktionieren erst ab Affiliate). Du musst auf Twitch eingeloggt sein, bevor du den Flow startest — sonst Zwischenschritt mit Twitch-Login. Flow Dashboard → Integrations → Twitch → « Verbinden » . Was im Hintergrund passiert: Browser geht an /oauth/twitch/start . Chatlix erzeugt einen state -Parameter (CSRF-Schutz), redirected zu https://id.twitch.tv/oauth2/authorize mit den nötigen Scopes. Du loggst dich (ggf.) bei Twitch ein und siehst eine Zustimmungs-Seite mit der Liste der Berechtigungen. « Authorize » schickt dich zurück an /oauth/twitch/callback . Chatlix tauscht den code gegen Access- und Refresh-Token, speichert sie verschlüsselt, registriert die nötigen EventSub-Subscriptions. Im Dashboard siehst du jetzt „Verbunden als “. Wenn das Dashboard nach dem Callback eine Fehlermeldung zeigt: siehe Seite Reauth + Token-Erneuerung . Was Chatlix tatsächlich anfordert Chatlix fragt nur die Scopes ab, die du wirklich brauchst — abhängig davon, welche Features du nutzt. Wenn du in deinem Plan zum Beispiel keine Moderator-Aktionen aktiviert hast, fragt Chatlix den Moderator-Scope auch nicht ab. Welche Scopes potenziell auftauchen können, steht auf der Seite Permissions verstehen . EventSub-Webhook Nach erfolgreicher Verbindung registriert Chatlix automatisch EventSub-Subscriptions für die Event-Typen, die du nutzt. Twitch sendet diese Events dann an /webhook/twitch/eventsub (Chatlix-API). Du musst dafür nichts konfigurieren. Wenn du Events vermisst (z. B. Sub-Alerts kommen nicht an): Dashboard → Integrations → Twitch → « Diagnose » . Zeigt alle aktiven Subscriptions an. Wenn dort etwas auf revoked oder failed steht: « Subscriptions neu registrieren » . Wenn das nicht hilft: Token könnte abgelaufen sein → Reauth. Mehrere Channels / Multi-Account Pro Chatlix-Account ist genau ein Twitch-Account verknüpft. Wenn du als Moderator für einen anderen Channel arbeitest: dein Twitch-Account muss dort als Moderator hinterlegt sein, dann kannst du die Moderator-Aktionen für diesen Channel ausführen (siehe Permissions verstehen ). Verbindung trennen Dashboard → Integrations → Twitch → « Trennen » . Das: löscht Access- und Refresh-Token aus Chatlix versucht, die EventSub-Subscriptions sauber abzumelden entzieht die App-Berechtigung auf Twitch-Seite nicht automatisch — das geht nur über die Twitch-Connections-Seite ( https://www.twitch.tv/settings/connections ) Automationen, die Twitch-Trigger nutzen, laufen nach dem Trennen nicht mehr — bleiben aber gespeichert, falls du später wieder verbindest. Häufige Probleme beim Verbinden „state mismatch“ — Cookies blockiert oder der Flow wurde in einem anderen Tab abgeschlossen. Im selben Browser, im selben Tab nochmal starten. „redirect_uri mismatch“ — du nutzt eine Custom-Domain, die nicht in der Twitch-App-Config steht. Sollte bei Standard-Setups nicht passieren; melde dich beim Support. „access_denied“ — du hast bei Twitch „Cancel“ geklickt. Nochmal starten und « Authorize » bestätigen. Permissions verstehen Permissions verstehen Wenn du Chatlix mit Twitch verbindest, fordert Chatlix bestimmte Scopes an — das sind die Rechte, die Twitch deinem Account für die Chatlix-App freigibt. Diese Seite erklärt, was jedes Recht bedeutet und wofür Chatlix es braucht. Wichtig: Chatlix fragt nur die Scopes an, die nötig sind für die Features, die du aktiviert hast. Du wirst also nicht zwangsweise alle aus der Liste unten sehen. Die Scopes im Detail channel:read:redemptions Was : liest Channel-Point-Reward-Einlösungen. Wofür : damit Chatlix mitbekommt, wann jemand einen Reward einlöst (z. B. „TTS abspielen“, „AI-Bild generieren“). Ohne diesen Scope funktioniert keine Reward-Automation. channel:manage:redemptions Was : anlegen, ändern, löschen von Channel-Point-Rewards. Plus: Reward-Einlösungen als FULFILLED oder CANCELED markieren. Wofür : damit du Rewards direkt aus dem Chatlix-Dashboard verwalten kannst und Chatlix nach erfolgreicher Aktion den Reward als erledigt markieren (oder bei Fehler refunden) kann. channel:read:subscriptions Was : liest deine Subscriber-Liste und neue Sub-Events. Wofür : Sub-Alerts, Sub-Goals, Sub-Counter im Overlay. chat:read Was : liest Chat-Nachrichten in deinem Channel. Wofür : Command-Reaktionen ( !befehl ), Chat-Filter-Trigger, Stream-Memory-Chat-Highlights. chat:edit Was : schreibt Chat-Nachrichten als dein Account. Wofür : Bot-Antworten, automatische Begrüßung, Reaktions-Nachrichten auf Events. Hinweis: Chatlix schreibt als dein Twitch-Account , nicht als separater Bot. Wenn du das nicht willst, lass diesen Scope weg und nutze einen eigenen Bot-Account, der separat verbunden wird. bits:read Was : liest Cheer-Events (Bits). Wofür : Bit-Alerts, Bit-Goals, Cheer-Trigger in Automationen. channel:manage:broadcast Was : Titel, Spiel, Tags des Streams ändern. Wofür : optional — z. B. Auto-Titel-Updates bei Game-Wechsel via Game-Watcher. Wenn du das nicht nutzt, brauchst du diesen Scope nicht. moderator:read:followers Was : liest die Follower-Liste (für Moderatoren, nicht öffentlich). Wofür : präzise Follower-Alerts mit Zeitstempel, Follow-Goals. Twitch hat 2023 den öffentlichen Follower-Endpoint abgeschafft — ohne diesen Scope siehst du Follows nur grob. Moderator-Aktionen Manche Aktionen kannst du nur ausführen, wenn du Moderator des Ziel-Channels bist (oder Broadcaster). Beispiele: Timeout / Ban Slow-Mode togglen Followers-Only togglen Shoutouts senden Chatlix prüft das beim Auslösen der Aktion: wenn dein Twitch-Account auf dem Ziel-Channel keine Moderator-Rolle hat, kommt ein ok:false, error=not_a_moderator zurück. Der Streamer / Broadcaster ist auf seinem eigenen Channel automatisch berechtigt — er muss sich nicht selbst zum Moderator machen. Scopes nachträglich erweitern Wenn du ein neues Feature aktivierst, das einen zusätzlichen Scope braucht (z. B. Bits-Alerts, nachdem du nur mit Subs angefangen hast), zeigt das Dashboard einen Banner: Dieses Feature braucht den Scope bits:read . Bitte Twitch neu verbinden. Dann den Flow aus Twitch verbinden erneut durchlaufen — Twitch zeigt nur die neuen Rechte zur Zustimmung an, die alten bleiben bestehen. Rechte einsehen / entziehen Auf Twitch direkt: https://www.twitch.tv/settings/connections . Dort siehst du die Chatlix-App und kannst sie komplett entziehen. Folge: Chatlix-Token wird invalidiert ( TWITCH_TOKEN_EXPIRED ), du wirst beim nächsten API-Call zur Reauth aufgefordert. Reauth + Token-Erneuerung Reauth + Token-Erneuerung Nach einer erfolgreichen Twitch-Verbindung bekommst du einen Access-Token (gültig ~4h) und einen Refresh-Token (langlebig). Chatlix erneuert den Access-Token automatisch im Hintergrund, sobald er abläuft. Solange das funktioniert, musst du nichts tun. Manchmal funktioniert es nicht. Diese Seite erklärt, wann und warum, und wie du es behebst. Was bedeutet TWITCH_TOKEN_EXPIRED Dieser Fehler erscheint im Dashboard und in Logs, wenn: der Access-Token abgelaufen ist und die automatische Erneuerung über den Refresh-Token fehlgeschlagen ist Mögliche Ursachen: Du hast Chatlix bei Twitch entzogen (Twitch-Settings → Connections → „Disconnect“). Refresh-Token ist damit ungültig. Twitch hat den Token invalidiert — zum Beispiel nach einem Passwort-Wechsel oder einem Security-Alert auf deinem Twitch-Account. Du hast dein Twitch-Passwort geändert — Twitch invalidiert dabei je nach Einstellung alle Drittanbieter-Token. Twitch-API-Outage während des Refresh-Versuchs. Chatlix versucht es periodisch erneut; meistens behebt sich das selbst. Was passiert in der Zwischenzeit Solange der Token expired ist: EventSub-Subscriptions laufen weiter, soweit Twitch sie noch ohne aktiven User-Token akzeptiert . Manche Event-Typen werden aber pausiert oder gehen ins revoked -Status. API-Aufrufe, die deinen User-Token brauchen (z. B. Chat-Posting via chat:edit , Reward-Management), schlagen fehl. Chatlix zeigt im Dashboard ein gelbes Banner: „Twitch-Verbindung abgelaufen — bitte neu verbinden“. Kein Datenverlust: deine Automationen, Regeln, gespeicherten Rewards bleiben unverändert. Reauth-Flow Dashboard → Integrations → « Twitch neu verbinden » . Der Ablauf ist identisch zum erstmaligen Verbinden (siehe Twitch verbinden ). Du wirst zu Twitch geschickt, bestätigst die Berechtigungen (Twitch erinnert sich an die alten — du klickst meist nur einmal „Authorize“), und kommst zurück. Chatlix tauscht Code gegen frische Token, registriert EventSub-Subscriptions neu, und das Banner verschwindet. Dauert insgesamt etwa 20 Sekunden. Wenn Reauth fehlschlägt „Access denied“ auf Twitch : du hast „Cancel“ geklickt. Nochmal starten. „redirect_uri mismatch“ : Custom-Domain-Konfigurationsproblem. Support kontaktieren. Sofortiges erneutes TWITCH_TOKEN_EXPIRED : dein Twitch-Account hat möglicherweise eine 2FA-Pflicht für API-Tokens, die in der App-Config fehlt. Support kontaktieren. Stiller Erfolg, aber Events fehlen weiter : Dashboard → Integrations → Twitch → « Diagnose » → « Subscriptions neu registrieren » . Twitch braucht manchmal einen expliziten Re-Subscribe nach Token-Wechsel. Automatische Erneuerung — wie sie intern läuft Für Interessierte: Chatlix prüft kurz vor jeder Twitch-API-Operation, ob der Access-Token noch gültig ist. Bei <5 Minuten Restlaufzeit wird er proaktiv erneuert. Refresh-Calls laufen über https://id.twitch.tv/oauth2/token mit grant_type=refresh_token . Bei Erfolg werden Access- und Refresh-Token rotiert und verschlüsselt gespeichert. Bei Fehler ( 400 invalid_grant o. ä.) wird der Token-Status auf expired gesetzt und das Dashboard-Banner aktiviert. Intern liegen die 7 Twitch-Service-Klassen unter Chatlix\Twitch\* . Der OAuth-Start-Endpoint ist /oauth/twitch/start , der Callback /oauth/twitch/callback , EventSub-Inbox /webhook/twitch/eventsub . Best Practices Kein Twitch-Passwort-Wechsel kurz vor einem wichtigen Stream . Wenn du es musst: danach 2 Minuten warten, ins Dashboard, Reauth. Bei „Verbindung trennen“ auf Twitch direkt : sofort danach im Chatlix-Dashboard Reauth durchführen, damit Automationen nicht stillschweigend ausfallen. Diagnose-Seite im Auge behalten — sie zeigt Subscriptions, ihren Status und das letzte erfolgreich empfangene Event pro Typ.