一個按鈕,執行您的工作流程

使用 Stream Deck、HTTP 或 WebSocket 執行已儲存的 Event Flow 工作流程。

完整 Stream Deck 控制項、手勢與圖示指南

建立可呼叫的工作流程

Event Flow命名工作流程Stream Deck鍵
Overview section of the Event Flow guide, explaining sources, logic nodes and actions.
Build and name the workflow in the Event Flow editor. Its built-in guide, shown here, explains sources, logic nodes and actions.
  1. 具名觸發器Stream Deck / API
  2. 條件與操作您儲存的 Event Flow
  3. 目標Flow Actions、OBS 或其他整合
  1. 開啟 Event Flow ,來自 SSN。建立專用流程或選擇 Stream Deck/API 按鈕 範本。
  2. 新增 從 Stream Deck/API 執行 ,位於 Stream Deck 與 API 觸發器群組。
  3. 將其命名為 intermission。名稱需精確比對且區分大小寫;請使用簡短且有描述性的名稱。
  4. 將其輸出連接至 顯示文字。將文字設為 Back in five minutes,並選擇所需的時長與圖層。
  5. 儲存流程,然後啟用。未儲存的流程只存在於編輯器中;已停用流程無法呼叫。入門範本會保持停用,直到您完成設定。
  6. 開啟您的 Flow Actions 疊加畫面 ,使用 SSN 產生的連結。面向觀眾時,將該 URL 新增為 OBS 瀏覽器來源。編輯器本身不是疊加畫面。

沒有此具名觸發器的流程無法透過工作流程 API 呼叫。呼叫工作流程不會向停駐面板注入模擬聊天。現有 OBS 事件與一般聊天繼續使用各自現有觸發器。

流程可透過邏輯節點將具名觸發器與篩選器組合。將無關自動化保留在不同流程中:選定流程中的所有觸發器/邏輯分支都會使用該 API 事件求值。重複按鍵會啟動獨立執行;如果需要冷卻,請放置一個 速率限制器 狀態節點,放在觸發器之後。

連接 Stream Deck 按鍵

  1. 設定外掛程式的 設定 操作,使用您的 SSN 工作階段與選用密碼。使用 測試連線.
  2. 拖曳 預設命令 至按鍵上。
  3. 選擇 Event Flow 工作流程 → 執行工作流程.
  4. 選擇 重新整理工作流程,然後選擇已儲存的流程與觸發器。按鍵會同時儲存流程 ID 與觸發器名稱。
  5. 按一次並觀察 Flow Actions 疊加畫面。按鍵上的勾號表示 SSN 已接受執行請求。

工作流程選擇器會保留已缺漏的選取。重新命名、停用、刪除或匯入流程後,請重新整理並重新選擇。作為新流程匯入的工作流程具有不同 ID。如需依名稱針對多個流程,請改用值欄位。

自訂命令: 將操作設為 triggerWorkflow,將目標留空,輸入 {"trigger":"intermission"} 作為值,並啟用 等待回應。預設提供引導式選擇與能力篩選。

多重操作: 每個工作流程請求都會快速確認接受。延遲工作流程操作完成前,下一步 Stream Deck 操作就可能啟動。順序重要時,請在 Event Flow 內安排執行順序與延遲。

傳遞自訂值

在按鍵的值欄位或 API 請求中:

{
  "trigger": "intermission",
  "flowId": "YOUR_SAVED_FLOW_ID",
  "data": { "name": "Back in five minutes", "minutes": 5 }
}

將顯示文字設為 {meta.workflow.data.name}。比較屬性可以讀取 meta.workflow.data.minutes。資料是選用的 JSON 物件,保留在 meta.workflow.data ,不能取代事件身分或授予聊天權限。

省略 flowId ,以呼叫具有完全相同觸發器名稱的每個已啟用流程。同一流程中的多個符合觸發器節點,仍只會讓該流程求值一次。只執行一個流程時,請保留選擇器或探索回應提供的流程 ID。

選定流程內使用的事件具有 type: "api", event: "workflow_trigger", chatname: "Stream Deck / API"、空的 chatmessage,以及上方資料。複製這些欄位的一般聊天無法啟用具名 API 觸發器。

API 範例

保持 SSN 啟用並執行。這些是 Social Stream 遠端控制呼叫,不使用 SSApp 獨立的本機 AI/MCP API。請保密真實工作階段 ID。

探索可用觸發器

{"action":"getWorkflowTriggers","get":"list-1","apiid":"YOUR_SESSION"}

回呼包含 result.payload.triggers:

{"triggers":[{"flowId":"flow-123","flowName":"Intermission","trigger":"intermission"}]}

執行具名工作流程

{
  "action": "triggerWorkflow",
  "value": {"trigger":"intermission","flowId":"flow-123","data":{"name":"Back shortly"}},
  "get": "run-1",
  "apiid": "YOUR_SESSION"
}

使用唯一的 get 字串,分別用於每個請求。成功的回呼具有 result.ok: true, result.status: "accepted",以及 result.payload.matchedFlows。接受表示已找到啟用的流程並安排執行,不代表每個延遲操作、Webhook、OBS 呼叫或媒體播放都已完成。

WebSocket

啟用 擴充功能的遠端 API 控制 ,在 SSN 中。連接至 wss://io.socialstream.ninja。使用下列內容加入: {"join":"YOUR_SESSION","out":1,"in":2}, then send the request above. Channel 1 carries controls; replies come back on channel 2. To get a reply over the hosted WebSocket, add "replyFormat":"commandResult" ,放在以下檔案旁: get. It arrives as {"type":"commandResult","action":"...","get":"...","result":{...}}. Without it, the relay keeps the older callback reply for HTTP requests and does not forward it to WebSocket clients. You do not need to enable the chat channel for workflows.

HTTP

啟用相同的遠端 API 控制設定。使用前取代工作階段預留位置:

POST https://io.socialstream.ninja/YOUR_SESSION
Content-Type: application/json

{"action":"triggerWorkflow","value":{"trigger":"intermission","data":{"name":"Back shortly"}}}

對於簡單的具名觸發器,也可使用 GET https://io.socialstream.ninja/YOUR_SESSION/triggerWorkflow/null/intermission。第四個路徑區段可包含經 URL 編碼的 JSON,以傳遞結構化值。使用下列函式編碼整個 JSON 值: encodeURIComponent(JSON.stringify(value))。自訂傳送通道使用 ?channel=N.

P2P

外掛程式預設的 P2P 模式透過 SSN 現有 VDO.Ninja 資料通道傳輸相同承載資料。P2P 無需啟用託管 WebSocket API 開關。現有 P2P 用戶端應透過已經建立的 SSN 控制連線傳送此請求;無需開啟本機 AI API。

錯誤與相容性

  • WORKFLOW_NOT_FOUND:沒有已儲存且啟用的流程符合該觸發器/流程 ID。
  • INVALID_VALUE:觸發器缺漏/無效、JSON 格式錯誤、流程 ID 無效,或資料不是物件。
  • CONTROL_UNAVAILABLE:SSN 或遠端主持人控制已停用。
  • TARGET_UNAVAILABLE:Event Flow 仍在載入。
  • 舊版 Social Stream 資源可能不會宣告這些操作。檢查 getCapabilities → ssn.actions.triggerWorkflow 和 getWorkflowTriggers。新觸發器與更新後的外掛程式都必須安裝;僅憑 SSApp 版本號無法識別遠端載入的 Social Stream 資源。

遺失確認後,不要自動重試會改變狀態的呼叫:工作流程可能已經啟動。先檢查輸出。此 API 不提供執行狀態佇列。

各整合需要什麼

工作流程操作所需目標/設定檢查內容
顯示文字、媒體、音訊、清除圖層已連線、使用相同工作階段的 Flow Actions 疊加畫面;觀眾輸出使用 OBS 瀏覽器來源。可見輸出、圖層、時長與音訊路由。命令成功並不能證明 OBS 場景可見。
OBS 控制項Flow Actions 使用設定的位址/密碼連線至 OBS;場景/來源名稱相符。實際 OBS 狀態。參閱 OBS 指南.
釘選/精選訊息已連線的預設停駐面板;選擇真實訊息 ID 或完整訊息承載資料。停駐面板釘選清單與精選疊加畫面。API 觸發器的空聊天文字本身並不是有用的聊天內容。
呼叫 Webhook操作中的 URL、方法與 JSON 請求本文。接收器回應與 Event Flow 錯誤欄位;Stream Deck 的確認會先於延遲/外部結果到達。
傳送訊息/中繼可寫且已連線的來源,以及明確的目標。實際目標聊天。工作流程請求並不意味著獲准繞過平台限制。
商品與支持已儲存/啟用的商品與電商疊加畫面。SSN 的選取/隱藏/排程狀態。參閱 商品控制項.
抽獎、票券、點數已設定的抽獎/經濟系統,以及合適的執行者。具名 API 事件沒有觀眾身分。主持人控制請使用主持人層級抽獎預設;不要將 API 事件當作觀眾購買。參閱 抽獎與點數.
TTS、Spotify、列印、MIDI各整合本身的連線、權限、裝置或帳號設定。實際目標/裝置。安裝 Stream Deck 不會自動設定這些整合。

完整 Event Flow 指南 · 實用方案 · API 參考

計時器與聊天手勢

計時器: 預設每轉一格調整 ±10 秒; 按住旋鈕並轉動 可調整 ±1 分鐘(設定步長的 6 倍)。不轉動時按下再放開可開始/暫停。點按計時器顯示螢幕可重新整理;長按 顯示螢幕 以重設。僅長按實體旋鈕不會重設。

聊天回顧: 向左轉查看較舊聊天,向右轉查看較新聊天;按下旋鈕可釘選目前回顧的訊息。點按顯示螢幕可精選下一則釘選訊息;長按顯示螢幕可取消釘選目前回顧的訊息。保持預設停駐面板開啟。WebSocket 模式下請啟用通道 4 的聊天中繼。

開啟 說明與診斷 → 控制項、圖示與工作流程指南 ,位於外掛程式中,查看完整離線指南、全部五種操作類型、每項預設/圖示、重設行為、預設值與疑難排解。

Event Flow 節點面板參考

節點面板包含 45 個觸發器、67 個操作、5 個邏輯節點與 4 個狀態節點。每個項目的符號旁都有文字標籤。選擇節點可查看設定與整合先決條件;面板圖示並不表明目標已連線。

觸發器 決定流程何時啟動。需要時用 AND/OR 連接條件。 操作 依連接順序執行。 狀態節點 在事件之間記住值。按鈕冷卻請選擇 速率限制器 (THROTTLE),而不是延遲操作:延遲會推遲每次執行,不會抑制重複按鍵。

觸發器:Stream Deck 與 API(1)
  • ▶ 從 Stream Deck/API 執行 — apiTrigger
觸發器:📣 直播事件(9)
  • 👋 新追蹤者 — eventNewFollower
  • ⭐ 新訂閱者 — eventNewSubscriber
  • 🔄 再次訂閱/續訂 — eventResub
  • 🎁 贈送訂閱 — eventGiftSub
  • 💰 捐款/贊助 — eventDonation
  • 🚀 揪團 — eventRaid
  • 💎 歡呼/Bits — eventCheer
  • 📋 其他事件… — eventOther
  • ✏️ 自訂事件 — eventCustom
觸發器:OBS Studio(7)
  • OBS 直播開始 — obsStreamStarted
  • OBS 直播停止 — obsStreamStopped
  • OBS 錄製開始 — obsRecordingStarted
  • OBS 錄製停止 — obsRecordingStopped
  • OBS 場景變更 — obsSceneChanged
  • OBS 媒體結束 — obsMediaEnded
  • OBS 重播緩衝區已儲存 — obsReplaybufferSaved
觸發器:💬 聊天訊息(6)
  • 💬 任意訊息 — anyMessage
  • 🔍 訊息包含 — messageContains
  • ▶️ 訊息開頭為 — messageStartsWith
  • ⏹️ 訊息結尾為 — messageEndsWith
  • 🟰 訊息等於 — messageEquals
  • 🔤 訊息正規表示式 — messageRegex
觸發器:📊 訊息屬性(7)
  • 📏 訊息長度 — messageLength
  • 🔢 詞數 — wordCount
  • 😀 包含 Emoji — containsEmoji
  • 🔗 包含連結 — containsLink
  • 💰 包含贊助 — hasDonation
  • ⚖️ 比較屬性 — compareProperty
  • ⚙️ 訊息屬性篩選器 — messageProperties
觸發器:👤 使用者與來源(6)
  • 📡 來自來源 — fromSource
  • 📺 來自頻道名稱 — fromChannelName
  • 👤 來自使用者 — fromUser
  • 👑 使用者角色 — userRole
  • 🧠 使用者已被記住 — userMemoryContains
  • 🎁 頻道點數兌換 — channelPointRedemption
觸發器:⏰ 定時與隨機(4)
  • 🎲 隨機機率 — randomChance
  • ⏰ 時間間隔 — timeInterval
  • 🎤 當我說… — voicePhrase
  • 🕐 一天中的時間 — timeOfDay
觸發器:🎹 MIDI(3)
  • 🎹 MIDI 音符開啟 — midiNoteOn
  • 🎹 MIDI 音符關閉 — midiNoteOff
  • 🎛️ MIDI 控制變更 — midiCC
觸發器:📦 進階(2)
  • 📣 事件類型(進階)— eventType
  • 自訂程式碼 — customJs
操作:💬 訊息操作(14)
  • 🚫 封鎖訊息 — blockMessage
  • ✅ 傳回訊息 — returnMessage
  • ⚡ 非同步繼續 — continueAsync
  • ✏️ 修改訊息 — modifyMessage
  • ⬅️ 新增前綴 — addPrefix
  • ➡️ 新增後綴 — addSuffix
  • 🔄 尋找與取代 — findReplace
  • ✂️ 移除文字 — removeText
  • 🎨 設定屬性 — setProperty
  • 🌟 精選訊息 — featureMessage
  • 釘選訊息 — pinMessage
  • 💬 傳送訊息 — sendMessage
  • 📢 中繼聊天 — relay
  • 🪞 回傳篩選器 — reflectionFilter
操作:🔌 整合(6)
  • 執行自訂程式碼 — customJs
  • 🖨️ 列印熱感應標籤 — printThermal
  • 🌐 呼叫 Webhook — webhook
  • ⬆️ 新增點數 — addPoints
  • ⬇️ 花費點數 — spendPoints
  • 🎁 抽獎/票券 — giveawayControl
操作:🎨 媒體與效果(7)
  • 🖼️ 顯示媒體疊加畫面 — playTenorGiphy
  • 👤 顯示大頭貼 — showAvatar
  • 🛍 商品與支持 — commerceControl
  • 📝 顯示文字 — showText
  • 🗑️ 清除圖層 — clearLayer
  • 🔊 播放音訊片段 — playAudioClip
  • ⏱️ 延遲 — delay
操作:🎬 OBS Studio(14)
  • 🎬 變更場景 — obsChangeScene
  • 👁️ 切換來源 — obsToggleSource
  • 📝 設定文字來源 — obsSetText
  • ⏯️ 控制媒體來源 — obsMediaControl
  • 🔊 設定來源音量 — obsSetVolume
  • 🔄 重新整理瀏覽器來源 — obsRefreshBrowser
  • 🎨 切換濾鏡 — obsSetSourceFilter
  • 🔇 靜音/取消靜音 — obsMuteSource
  • 🔴 開始錄製 — obsStartRecording
  • ⏹️ 停止錄製 — obsStopRecording
  • 📡 開始直播 — obsStartStreaming
  • ⏹️ 停止直播 — obsStopStreaming
  • ⏺️ 控制重播緩衝區 — obsReplayBufferControl
  • 💾 儲存重播緩衝區 — obsReplayBuffer
操作:🎵 Spotify(10)
  • ⏭️ 略過曲目 — spotifySkip
  • ⏮️ 上一首 — spotifyPrevious
  • ⏸️ 暫停 — spotifyPause
  • ▶️ 恢復 — spotifyResume
  • ⏯️ 切換播放/暫停 — spotifyToggle
  • 🔊 設定音量 — spotifyVolume
  • 📋 新增至佇列 — spotifyQueue
  • 🎵 公告正在播放 — spotifyNowPlaying
  • 🔀 切換隨機播放 — spotifyShuffle
  • 🔁 設定重複模式 — spotifyRepeat
操作:🔊 文字轉語音(5)
  • 🗣️ 朗讀文字 — ttsSpeak
  • 🔇 切換 TTS — ttsToggle
  • ⏭️ 略過 TTS — ttsSkip
  • 🗑️ 清空 TTS 佇列 — ttsClear
  • 🔊 設定 TTS 音量 — ttsVolume
操作:🎹 MIDI(2)
  • 🎹 傳送音符 — midiSendNote
  • 🎛️ 傳送控制變更 — midiSendCC
操作:🧠 使用者記憶(4)
  • 🧠 記住使用者 — rememberUser
  • 👋 忘記使用者 — forgetUser
  • 🧹 清除所有使用者 — clearUserMemory
  • 🎟️ 隨機選擇使用者 — pickRandomUser
操作:🔧 狀態控制(5)
  • 🚦 設定閘狀態 — setGateState
  • 🔄 重設狀態節點 — resetStateNode
  • 🔢 設定計數器值 — setCounter
  • ➕ 增加計數器 — incrementCounter
  • 檢查計數器 — checkCounter
邏輯與狀態節點
  • 🔀 及閘 — AND
  • 🔄 或閘 — OR
  • 🚫 反閘 — NOT
  • 🎲 隨機閘 — RANDOM
  • 🚫 檢查不當詞語 — CHECK_BAD_WORDS
  • 🚦 開/關開關 — GATE
  • 🔢 計數器 — COUNTER
  • ⏲️ 速率限制器 — THROTTLE
  • 🧠 使用者記憶 — USER_MEMORY

訊息篩選器、觀眾點數與已記住使用者的操作需要有意義的訊息/使用者資料。主持人按鈕既不提供真實觀眾,也不提供來源回覆目標。選擇主持人控制或明確設定的目標;不要使用具名工作流程冒充觀眾。

詳細連接說明,請參閱 Event Flow 指南, 狀態節點指南, 使用者記憶指南,以及 OBS 指南.

逐步排查失敗

  1. 先使用簡單的顯示文字流程,並驗證其輸出。
  2. 儲存並啟用;重新整理 Stream Deck 工作流程清單。確認觸發器名稱與流程 ID。
  3. 確認 SSN 已啟用、連線狀態為線上,且目標疊加畫面連線至相同工作階段。
  4. 檢查 API 回呼或外掛程式診斷中的查找/驗證錯誤。請求被接受後發生的失敗,請檢查目標與 Event Flow 執行階段記錄。
  5. 逐一新增更多整合。正式使用前,測試重複按鍵、停用流程與重新連線。

編輯器的一般聊天測試面板傳送聊天事件,不會模擬具名 API 觸發器。透過 Stream Deck 或 API 測試此觸發器,以驗證完整路徑。