Verfuegbare Aktionen

Diese Seite listet die tatsächlichen, im Code vorhandenen Endpunkte unter /v1/streamdeck/ — geprüft direkt gegen und die zugehörige Runbook-Doku. Frühere Wiki-Versionen nannten Aktionen wie „Reward triggern", „StoryQuest-Choice setzen", „Counter inkrementieren" oder einen simulierten „Hype-Train" — diese existieren in der API nicht. Halt dich an die Liste unten.

Der generische Dispatcher: POST /v1/streamdeck/execute

Das ist der zentrale Endpoint für Hardware-Decks und Automatisierungs-Tools. Request-Format:

{
  "action": "soundboard_play",
  "body": { "sound_id": 42 }
}

Nur folgende action-Werte sind erlaubt (Whitelist StreamDeckService::ALLOWED_ACTIONS):

Action	Body-Schema	Min-Scope	Was passiert
macro_trigger	{slug: string}	macros	Triggert ein Macro per Slug. Macro muss dir gehören, sonst not_found (404).
soundboard_play	{sound_id: int}	macros	Spielt einen Sound aus der Media Library. volume_override/respect_cooldown existieren NICHT im Dispatcher (nur sound_id wird gelesen, Cooldown-Check ist serverseitig fest aktiv). Antwort enthält correlation_id für Audit-Nachverfolgung.
overlay_test_alert	{overlay_id?: int, alert_type?: overlay_burst\|follow\|sub\|raid\|cheer\|donation}	full	Nur Test/Simulation — feuert eine Test-Alert-Animation im Overlay, löst kein echtes Twitch-Event aus. Default overlay_burst.
panic_toggle	{}	full	Wechselt Panic-Mode an/aus. Antwort: toggled_to.
panic_enable	{ttl_sec?: 60-3600, reason?: string}	full	Aktiviert Panic-Mode, Default-TTL 600s, danach automatische Deaktivierung.
panic_disable	{}	full	Deaktiviert Panic-Mode sofort.

Rate-Limit: 5 Requests/Sekunde pro Token (Redis, eigener Bucket je Token). Response-Shape bei Erfolg: das Subsystem-Ergebnis direkt als Top-Level-JSON (kein Envelope), z.B. {"ok":true,"correlation_id":"sb-…","sound_id":42}. Bei Fehler: {"ok":false,"code":"…", …}.

Weitere Bearer-Endpunkte (nicht Teil des Dispatchers)

Zusätzlich zum generischen /execute gibt es dedizierte Routen, die direkter angesprochen werden — praktisch, wenn deine Deck-Software mehrere fest verdrahtete Buttons statt eines generischen Action-Pickers hat:

• GET /v1/streamdeck/me — Account-Infos für das aufrufende Token (z.B. für Status-Anzeige in der Mobile-App).
• GET /v1/streamdeck/sounds — Liste deiner Soundboard-Assets samt IDs (für soundboard_play).
• POST /v1/streamdeck/clip — Clip-Aktion (Twitch-Clip erstellen).
• POST /v1/streamdeck/push/register / POST /v1/streamdeck/push/unregister — APNs-Push-Registrierung, genutzt von der Chatlix-Mobile-App, nicht von Hardware-Decks.
• POST /v1/streamdeck/mod/{verb} (Scope full) — Chat-Moderation direkt vom Deck. Erlaubte {verb}-Werte: timeout, ban, unban, clear, slow/slowoff, emoteonly/emoteonlyoff, followersonly/followersonlyoff, subscribersonly/subscribersonlyoff. Voraussetzung: Twitch-Kanal an deinen Chatlix-Account gebunden (bot_instances), sonst channel_not_bound.
• GET /v1/streamdeck/activity — normalisierter Activity-Feed (Events der letzten Zeit).
• GET /v1/streamdeck/timelines — Liste deiner Timelines.
• POST /v1/streamdeck/timelines/{id}/run — führt eine komplette Timeline aus, Antwort enthält steps_executed und duration_ms.
• POST /v1/streamdeck/shoutout — löst einen Shoutout für einen Kanal aus.
• POST /v1/streamdeck/chat/send / GET /v1/streamdeck/chat/recent — Chat-Nachricht als Bot senden bzw. letzte Nachrichten abrufen.
• GET /v1/streamdeck/macros — Liste deiner Macros (inkl. Built-ins BRB/Hype/Raid Incoming/Stream Start).
• POST /v1/streamdeck/macros/{slug}/trigger — direkter Trigger per Slug (Kurzform zu execute mit macro_trigger).
• GET /v1/streamdeck/status — Gesamtstatus (Stream live/offline, Connect-Verbindung etc.) für App-Dashboards.
• POST /v1/streamdeck/obs/{verb} (Scope full) — dispatcht als obs_<verb> an die OBS-Control-Schicht (Szenen, Quellen, Audio je nach implementiertem Verb).

Token-Verwaltung (Session-Auth, nicht Bearer)

• GET /v1/streamdeck/tokens — deine aktiven Tokens (mit Suffix, Scope, last_used_at).
• POST /v1/streamdeck/tokens — neues Token erzeugen, {name, scope}.
• DELETE /v1/streamdeck/tokens/{id} — Token widerrufen.

Der Control-Deck-Pfad (Web-Buttons, kein Token nötig)

POST /v1/control-deck/buttons/{id}/execute läuft über deine normale Dashboard-Session statt über ein Bearer-Token. Action und Konfiguration kommen dabei aus dem gespeicherten Button-Datensatz, nicht aus dem Request-Body. Das ist der Weg für die „▶ Trigger"/„▶ Run"-Buttons direkt im Dashboard (Tabs Macros/Timelines) — kein zusätzliches Token, keine Deck-Hardware nötig.

Ausdrücklich NICHT unterstützt

Folgende Action-Typen sind bewusst nicht in der Whitelist und werden mit 400 unknown_action abgewiesen:

• lighting_* (Pulse/Set-Color/Scene) — Lighting läuft ausschließlich über die Automation-Engine, damit Trace/Audit-Log (lighting_dispatch_log) konsistent bleibt. Alternative: Lighting per Automation-Regel triggern, ausgelöst z.B. über macro_trigger.
• tts_speak — TTS hat einen eigenen Pre-Charge-Check (Kosten pro Zeichen/Provider); Direct-Dispatch würde den umgehen. Alternative: Automation-Action „Text vorlesen" (Worker-Pfad).
• cinematic_fire — Cinematic-Pipeline ist Worker-only und braucht Bridge-/Stream-Memory-Kontext. Alternative: Automation-Action für Cinematics.
• Direct-Render von Overlay-Bursts — nur über overlay_test_alert erlaubt, kein eigener Render-Bypass.
• Token-Selbstverwaltung (Widerruf, Logout) — bewusst nicht über den Bearer-Pfad, sondern nur über die Session-Routen /v1/streamdeck/tokens.
• Channel-Points-Reward-Trigger, StoryQuest-Choice, Counter-Inkrement, echter Hype-Train — es gibt keinen Endpoint dafür. Für Rewards nutz die Reward-Testfunktion direkt im Rewards-Dashboard; für StoryQuest die Live-Session-Steuerung im StoryQuest-Book.

Fehlercodes im Überblick

Code	HTTP	Bedeutung
no_bearer	401	Authorization-Header fehlt/falsches Format.
invalid_bearer	401	Token unbekannt, abgelaufen oder deaktiviert.
insufficient_scope / scope_full_required	403	Token-Scope reicht nicht für die Aktion.
unknown_action	400	action nicht in der Whitelist; Response listet allowed.
missing_slug / missing_sound_id	400	Pflichtfeld im Body fehlt.
rate_limited	429	>5 Calls/Sek pro Token, Header Retry-After: 1.
dispatcher_unavailable	503	Subsystem (Macros/Soundboard/PanicMode/TestDispatch) wirft Exception.
sound_not_found_or_not_owned	200, ok:false	Sound existiert nicht oder gehört anderem Account.
cooldown_active	200, ok:false	Sound-Cooldown noch aktiv, wait_ms und scope in Response (nicht cooldown_remaining_ms).
not_found	404, ok:false	Macro-Slug existiert nicht.
channel_not_bound	400	Nur Mod-Aktionen: kein Twitch-Kanal an den Account gebunden.

Fachliche Fehler (Sound-Lookup, Cooldown) kommen bewusst als HTTP 200 + ok:false zurück, damit Automations-Tools sie nicht als Netzwerkfehler interpretieren und blind wiederholen. Auth- und Schema-Fehler bleiben echte 4xx-Codes, damit Konfigurationsfehler in der Deck-Software auffallen.

Logs prüfen

Im Dashboard /dashboard/streamdeck → Tab Verlauf siehst du die letzten 30 Aktionen (OBS- und Deck-Aktionen gemeinsam): Zeitstempel, Aktion, Status (ok/fail), Dauer in ms. Serverseitig landet jeder Call zusätzlich in chatlix_obs_action_log mit action_type = deck_<action> und einem _source-Marker (streamdeck_plugin für den Bearer-Pfad, control_deck für Web-Buttons) — hilfreich, wenn du unterscheiden willst, ob eine Aktion vom physischen Deck oder von einem Dashboard-Button kam.

Zurück zu StreamDeck Grundlagen für den Überblick, oder Setup für die Einrichtung von Grund auf.