Direkt zum Hauptinhalt

Twitch verbinden

Um Twitch-Events (Subs, Bits, Rewards, Follower, Polls, Hype Train, Chat) in Chatlix zu nutzen, musst du deinen Twitch-Account einmalig verbinden. Das läuft über den offiziellen Twitch-OAuth-Flow (Authorization Code Grant) — du wirst auf twitch.tv weitergeleitet, bestätigst dort die angeforderten Rechte, und kommst zurück ins Dashboard.

Voraussetzungen

  • Aktiver Chatlix-Account mit Streamer-Rolle.
  • Twitch-Account (Affiliate- oder Partner-Status ist nicht zwingend, aber Subs / Bits-Alerts funktionieren erst ab Affiliate, weil Twitch diese Features Nicht-Affiliates gar nicht erst freigibt).
  • Du musst auf Twitch eingeloggt sein, bevor du den Flow startest — sonst kommt ein Zwischenschritt mit Twitch-Login.

Flow

Dashboard → Integrations → Twitch → « Verbinden ».

Was im Hintergrund passiert (technisch, für den Fall, dass etwas schiefgeht und du die Fehlermeldung einordnen willst):

  1. Browser geht an /oauth/twitch/login (nicht /start — falls du diesen Pfad irgendwo notiert hast, ist er veraltet).
  2. Chatlix erzeugt einen zufälligen state-Wert und legt ihn in Redis unter dem Schlüssel twitch:state:<state> ab, zusammen mit einem JSON-Payload (u. a. mode, deine user_id, ggf. ein invite_code und die return_to-URL, zu der du nach Abschluss zurückkommst). Dieser Redis-Eintrag läuft nach kurzer Zeit automatisch ab — daher der Zwang, den Flow zügig abzuschließen.
  3. Redirect zu https://id.twitch.tv/oauth2/authorize mit den nötigen Scopes (siehe Permissions verstehen) und der Redirect-URI https://chatlix.app/oauth/twitch/callback.
  4. Du loggst dich (ggf.) bei Twitch ein und siehst die Zustimmungs-Seite mit der Liste der Berechtigungen.
  5. « Authorize » schickt dich zurück an /oauth/twitch/callback. Chatlix prüft dort zuerst den state gegen den Redis-Eintrag — passt er nicht, bricht der Flow mit dem Fehlercode oauth_state_invalid ab (siehe unten).
  6. Chatlix tauscht den code gegen Access- und Refresh-Token, speichert beide verschlüsselt in der Datenbank (twitch_accounts, Felder access_token_ciphertext / refresh_token_ciphertext) und registriert die nötigen EventSub-Subscriptions.
  7. Im Dashboard siehst du jetzt „Verbunden als <dein-twitch-name>“.

Wenn das Dashboard nach dem Callback eine Fehlermeldung zeigt: siehe Seite Reauth + Token-Erneuerung.

Was Chatlix tatsächlich anfordert

Chatlix fragt beim ersten Connect standardmäßig eine feste Liste von 19 Scopes an — nicht mehr nur „die, die du gerade brauchst“. Diese Liste ist über mehrere Feature-Ausbaustufen gewachsen. Details und die vollständige Scope-Liste stehen auf der Seite Permissions verstehen. Manche fortgeschrittenen Features (z. B. Ad-Break-Automation, VIP-Verwaltung) prüfen zusätzlich beim tatsächlichen Aufruf, ob der nötige Scope vorhanden ist, und zeigen sonst gezielt einen Reconnect-Hinweis.

EventSub-Webhook

Nach erfolgreicher Verbindung registriert Chatlix automatisch EventSub-Subscriptions für die Event-Typen, die dein Scope-Set erlaubt. Twitch sendet diese Events per Webhook (nicht per WebSocket — Chatlix nutzt die klassische serverseitige EventSub-Variante) an einen der beiden folgenden Endpunkte, die es aktuell parallel gibt:

  • /webhook/twitch/eventsub — der ältere, historisch gewachsene Endpoint.
  • /v1/twitch/eventsub/webhook — der versionierte Nachfolge-Endpoint.

Beide verifizieren eingehende Requests per HMAC-Signatur gegen ein Secret (aus /run/secrets/eventsub_secret oder einer Umgebungsvariable). Du musst dafür nichts konfigurieren — das ist reine Serverseite.

Zu den tatsächlich registrierten Event-Typen gehören unter anderem: Reward-Einlösungen, Follows, Polls (Start/Fortschritt/Ende), Hype-Train-Phasen, Subs/Resubs/Gift-Subs, Cheers (Bits), Chat-Notifications (u. a. für die Erkennung von Prime-Subs) und Ad-Break-Start. Nicht enthalten sind aktuell Prediction-Events — falls du Predictions in Automationen nutzen willst, funktioniert das derzeit nicht über EventSub-Trigger.

Wenn du Events vermisst (z. B. Sub-Alerts kommen nicht an):

  1. Dashboard → Integrations → Twitch → « Diagnose ». Zeigt alle aktiven Subscriptions an.
  2. Wenn dort etwas auf revoked oder failed steht: « Subscriptions neu registrieren ».
  3. Wenn das nicht hilft: Der zugrundeliegende Access-Token ist wahrscheinlich ungültig geworden → Reauth (siehe Reauth + Token-Erneuerung).

Bot-Account (Chat-Schreiben)

Anders als man vermuten könnte, schreibt Chatlix Chat-Nachrichten (Bot-Antworten, Begrüßungen, Reaktions-Nachrichten) standardmäßig nicht als dein eigener Twitch-Account, sondern über einen zentral konfigurierten, eigenen Bot-Account (chatlix_bot). Es gibt dafür keinen eigenen OAuth-Flow, den du selbst durchläufst — der Bot-Account ist plattformseitig über eine feste Account-ID hinterlegt. Damit der Bot in deinem Channel Nachrichten schreiben und (bei entsprechenden Scopes) moderieren kann, muss er dort als Moderator eingetragen sein. Ist der Bot-Account nicht konfiguriert, liefert die interne Schnittstelle den Fehlercode bot_account_not_configured. Moderator-Aktionen (Timeout, Ban, Slow-Mode etc.) kann Chatlix wahlweise über deinen eigenen Broadcaster-Token oder über den Bot-Account ausführen, sofern der Bot Moderator-Rechte im Ziel-Channel hat.

Mehrere Channels / Multi-Account

Pro Chatlix-Account ist genau ein Twitch-Account (dein Streamer-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 entsprechenden Moderator-Aktionen für diesen Channel ausführen (siehe Permissions verstehen). Der Chat-schreibende Bot-Account (siehe oben) ist davon unabhängig und plattformweit derselbe.

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

  • oauth_state_invalid (früher im Dashboard oft ungenau als „state mismatch“ beschrieben) — der in Redis hinterlegte state-Wert passt nicht mehr zum Callback. Häufigste Ursachen: Cookies/Storage blockiert, der Flow wurde in einem anderen Tab/Browser abgeschlossen, oder der Redis-Eintrag ist schlicht abgelaufen, weil zwischen Start und Abschluss zu viel Zeit vergangen ist. Im selben Browser, im selben Tab zügig neu starten.
  • „redirect_uri mismatch“ — die tatsächliche Redirect-URI weicht von https://chatlix.app/oauth/twitch/callback ab, z. B. bei Custom-Domain-Setups. Sollte bei Standard-Setups nicht passieren; melde dich beim Support.
  • „access_denied“ — du hast bei Twitch „Cancel“ geklickt. Nochmal starten und « Authorize » bestätigen.
  • „missing_scope“ bei einer konkreten Aktion (z. B. beim Anlegen eines Custom Rewards) — Twitch selbst lehnt die Aktion ab, weil ein Scope fehlt. Erkennst du daran, dass die Fehlermeldung sich auf eine einzelne Aktion bezieht, nicht auf den Connect-Vorgang insgesamt. Abhilfe: Reconnect, damit Chatlix den fehlenden Scope nachfordert (siehe Permissions verstehen).