Direkt zum Hauptinhalt

Setup

Dieser Leitfaden bringt dich von „Token angelegt" zu „erste Chatlix-Aktion läuft per Tastendruck". Lies vorher StreamDeck Grundlagen, wenn dir der Unterschied zwischen Bearer-Pfad (Hardware/Mobile) und Control-Deck-Pfad (Web-Buttons im Dashboard) noch nicht klar ist — es gibt kein fertiges Elgato-Plugin zum Herunterladen, du verkabelst die HTTP-Aktion selbst.

0. Voraussetzung: Plan prüfen

Macros & Stream-Deck ist ein Pro-Tier-Feature. Prüf auf /dashboard/streamdeck, ob dir das Anlegen eines Tokens angeboten wird. Free-Accounts bekommen 0 Token-Slots — da endet der Weg an dieser Stelle mit einem Plan-Upgrade-Hinweis, nicht mit einem technischen Fehler.

1. Token anlegen

Im Dashboard /dashboard/streamdeck → Tab Hardware-Tokens:

  • Name vergeben, z.B. „Stream Deck Hauptrechner".
  • Scope wählen: macros reicht für Sound/Macro-Trigger. Wenn du auch Panic-Mode, Test-Alerts, Chat-Moderation oder OBS-Steuerung über den Deck-Pfad willst, nimm full (enthält macros automatisch mit).
  • Token einmal kopieren — es wird danach nur noch gehasht gespeichert und ist nicht mehr im Klartext abrufbar.

API-Pendant: POST /v1/streamdeck/tokens mit {"name":"Stream Deck Hauptrechner","scope":"macros"} (Session-Auth, Dashboard-Cookie). Token-Kontingent ist plan-gestaffelt (Pro = 3, Studio = 10) — bei „quota exceeded" zuerst ungenutzte alte Tokens im Tab löschen.

2. Deck-Software mit einer HTTP-Request-Aktion einrichten

Da es kein Chatlix-.sdPlugin gibt, brauchst du in deiner Deck-Software eine Aktion, die einen HTTP-POST mit Custom-Header absetzen kann:

  • Elgato Stream Deck: Die Stock-Software hat keine native „POST mit Header"-Aktion. Nutz ein Community-Plugin, das das kann (z.B. ein generisches „Website/API-Call"-Plugin aus dem Marketplace), oder route über Touch Portal / Companion, die beide native Web-Request-Aktionen mit Custom-Headern mitbringen und sich per Plugin an dein Stream Deck koppeln lassen.
  • Touch Portal: Aktion „Web Request" → Methode POST, URL https://chatlix.app/v1/streamdeck/execute, Header Authorization: Bearer <dein Token> und Content-Type: application/json, Body siehe Schritt 3.
  • Eigenes kleines Script/Companion-Modul: Wenn deine Deck-Software gar keine HTTP-Aktion kann, reicht ein winziges lokales Script (z.B. Python mit requests), das die Taste per Tastenkombination/Hotkey auslöst und den curl-Call macht.

Alternative ohne Fremd-Plugin: Nutz stattdessen die Control-Deck-Web-Buttons direkt im Chatlix-Dashboard (Tab „Macros" bzw. „Timelines" — dort gibt es „▶ Trigger"/„▶ Run"-Buttons ohne jede Hardware). Das ist der pragmatischste Einstieg, wenn dir das Fremd-Plugin-Gefrickel zu viel ist.

3. Erste Aktion testen (Soundboard)

Bevor du irgendwas in der Deck-Software verkabelst, test den Call einmal direkt mit curl — das spart dir Rätselraten, ob der Fehler am Token oder an der Deck-Konfig liegt:

curl -X POST https://chatlix.app/v1/streamdeck/execute \
  -H "Authorization: Bearer <dein Token>" -H "Content-Type: application/json" \
  -d '{"action":"soundboard_play","body":{"sound_id":42}}'
# 200 -> {"ok":true,"sound_id":42,"correlation_id":"sb-2026-05-23-abc"}

Die sound_id findest du über GET /v1/streamdeck/sounds (mit demselben Bearer-Token) oder in der Media Library im Dashboard. Wenn der Call 200 mit ok:true zurückgibt, hörst du den Sound in jedem aktiven Overlay — dein OBS mit Chatlix-Browser-Source muss dafür laufen.

Trage danach dieselbe URL, denselben Header und denselben Body in deine Deck-Software ein und leg die Taste auf einen freien Button.

4. Macro statt Einzel-Sound

Für mehrschrittige Aktionen (z.B. „BRB": Szene wechseln + Sound + Overlay-Text) nutz nicht soundboard_play direkt, sondern ein Macro:

  • Im Tab „Macros" existieren die Built-ins BRB, Hype, Raid Incoming, Stream Start automatisch — verkette sie mit einer Timeline im Tab „Timelines", falls sie mehrere Schritte ausführen sollen.
  • Trigger per Deck: {"action":"macro_trigger","body":{"slug":"brb"}} gegen /v1/streamdeck/execute, oder direkt POST /v1/streamdeck/macros/<slug>/trigger.
  • Alternativ eine ganze Timeline: POST /v1/streamdeck/timelines/<id>/run. Antwort enthält steps_executed und duration_ms — praktisch zum Prüfen, ob wirklich alle Schritte gelaufen sind.

5. Panic-Mode und Moderations-Tasten (Scope full)

Mit einem full-Token kannst du zusätzlich heikle Nottasten belegen:

  • Panic-Mode: {"action":"panic_enable","body":{"ttl_sec":300,"reason":"clip incoming"}} — schaltet sich nach Ablauf der TTL (Default 600s) automatisch wieder ab. panic_disable beendet ihn sofort, panic_toggle wechselt den Zustand.
  • Chat-Moderation direkt vom Deck: POST /v1/streamdeck/mod/timeout, /mod/ban, /mod/unban, /mod/clear, /mod/slow (und die jeweiligen *off-Varianten für emoteonly/followersonly/subscribersonly). Voraussetzung: dein Chatlix-Account hat einen gebundenen Twitch-Kanal (bot_instances-Eintrag) — ohne den kommt channel_not_bound zurück.
  • Leg solche Tasten auf eine eigene, „versteckte" Deck-Seite/Folder — nicht neben Sound-Buttons, damit du sie nicht aus Versehen drückst.

6. OBS-Steuerung über den Deck-Pfad

POST /v1/streamdeck/obs/<verb> (Scope full) spiegelt echte OBS-Aktionen (Szenenwechsel, Quellen-Sichtbarkeit etc.) über Chatlix Connect. Für granulare Steuerung mit Dropdowns statt Freitext nutz stattdessen den Tab OBS Quick auf /dashboard/streamdeck oder die volle Oberfläche /dashboard/obs-control — dort siehst du auch, ob Connect aktuell verbunden ist, bevor du überhaupt einen Deck-Button drückst.

7. Mobile-App (Chatlix Mobile Deck) statt Hardware

Wenn du kein physisches Deck hast: Die Chatlix-iOS-App nutzt dieselbe Bearer-API und registriert sich zusätzlich für Push-Benachrichtigungen (POST /v1/streamdeck/push/register mit APNs-Token). Melde dich in der App mit demselben Chatlix-Account an, den auch deine Hardware-Tokens gehören — die App zieht dann Sounds, Macros und Status (GET /v1/streamdeck/status) automatisch.

8. Buttons/Seiten strukturieren

  • Erste Seite: die 5–10 häufigsten Aktionen (Soundboard, Haupt-Macros).
  • Folder „Sounds" für das komplette Soundboard.
  • Folder „Timelines" für mehrschrittige Sequenzen.
  • Folder „Mod/Panic" für die heiklen full-Scope-Aktionen aus Schritt 5 — bewusst eine Ebene tiefer.

9. Mehrere Geräte

Pro Gerät (Hauptrechner, Laptop, zusätzliches Mobile-Deck) ein eigenes Token anlegen — begrenzt durch dein Plan-Kontingent (Pro 3 / Studio 10). Vorteil: Ein verlorenes oder weitergegebenes Gerät kannst du einzeln über „Widerrufen" im Tab „Hardware-Tokens" sperren, ohne die anderen zu beeinträchtigen.

Troubleshooting

  • no_bearer (401): Authorization-Header fehlt oder hat kein Bearer -Prefix. Prüf die Deck-Software-Konfig auf exaktes Header-Format.
  • invalid_bearer (401): Token unbekannt, abgelaufen (TTL 365 Tage) oder im Dashboard bereits widerrufen. Neues Token anlegen, in der Deck-Software austauschen.
  • insufficient_scope / scope_full_required (403): Dein Token hat Scope macros, die Aktion (Panic, Test-Alert, Mod-Aktionen, OBS) verlangt full. Neues Token mit Scope full anlegen — Scope lässt sich nicht nachträglich ändern.
  • unknown_action (400): Der action-Wert im Body ist nicht in der Whitelist. Antwort enthält ein allowed-Array mit den tatsächlich unterstützten Werten — vergleich mit Verfuegbare Aktionen.
  • missing_slug / missing_sound_id (400): Body unvollständig — macro_trigger braucht slug, soundboard_play braucht sound_id.
  • cooldown_active (200, ok:false): Sound hat noch aktiven Cooldown. Antwort liefert wait_ms und scope (nicht cooldown_remaining_ms) — kein Fehler, sondern erwartetes Verhalten.
  • rate_limited (429): Mehr als 5 Calls/Sekunde über dasselbe Token. Bei Doppel-Klicks auf dieselbe Taste in der Deck-Software prüfen, ob die Software den Call mehrfach feuert.
  • channel_not_bound (400, nur Mod-Aktionen): Dein Chatlix-Account hat keinen aktiven Twitch-Bot-Kanal verbunden — zuerst unter Twitch-Setup den Bot binden.
  • Sound spielt nicht, obwohl ok:true: Overlay-Browser-Source in OBS nicht aktualisiert oder Chatlix Connect getrennt. Im Dashboard /dashboard/overlays den Verbindungsstatus prüfen.
  • Taste reagiert verzögert: Netzwerk-Latenz zwischen Deck-Rechner und chatlix.app prüfen. Normal <200ms; bei 1s+ liegt es meist am lokalen Netz, nicht an Chatlix.

Weiter zu Verfuegbare Aktionen für die vollständige Endpoint-Referenz, oder zurück zu StreamDeck Grundlagen für den konzeptionellen Überblick.