构建可调用的工作流程

- 命名触发器Stream Deck / API
- 条件与操作您保存的 Event Flow
- 目标Flow Actions、OBS 或其他集成
- 打开 Event Flow ,来自 SSN。创建专用流程或选择 Stream Deck/API 按钮 模板。
- 添加 从 Stream Deck/API 运行 ,位于 Stream Deck 与 API 触发器组。
- 将其命名为
intermission。名称需精确匹配且区分大小写;请使用简短且有描述性的名称。 - 将其输出连接到 显示文字。将文字设为
Back in five minutes,并选择所需的时长和图层。 - 保存流程,然后启用。未保存的流程只存在于编辑器中;已禁用流程无法调用。入门模板会保持禁用,直到您完成设置。
- 打开您的 Flow Actions 叠加层 ,使用 SSN 生成的链接。面向观众时,将该 URL 添加为 OBS 浏览器来源。编辑器本身不是叠加层。
没有此命名触发器的流程无法通过工作流程 API 调用。调用工作流程不会向停靠面板注入模拟聊天。现有 OBS 事件和普通聊天继续使用各自现有触发器。
流程可通过逻辑节点将命名触发器与筛选器组合。将无关自动化保留在不同流程中:选定流程中的所有触发器/逻辑分支都会使用该 API 事件求值。重复按键会启动独立运行;如果需要冷却,请放置一个 速率限制器 状态节点,放在触发器之后。
连接 Stream Deck 按键
- 配置插件的 设置 操作,使用您的 SSN 会话和可选密码。使用 测试连接.
- 拖动 预设命令 到按键上。
- 选择 Event Flow 工作流程 → 运行工作流程.
- 选择 刷新工作流程,然后选择已保存的流程和触发器。按键会同时保存流程 ID 和触发器名称。
- 按一次并观察 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 不会自动配置这些集成。 |
计时器和聊天手势
计时器: 默认每转一格调整 ±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 指南.
逐步排查失败
- 先使用简单的显示文字流程,并验证其输出。
- 保存并启用;刷新 Stream Deck 工作流程列表。确认触发器名称和流程 ID。
- 确认 SSN 已启用、连接状态为在线,且目标叠加层连接到相同会话。
- 检查 API 回调或插件诊断中的查找/验证错误。请求被接受后发生的失败,请检查目标和 Event Flow 运行日志。
- 逐一添加更多集成。正式使用前,测试重复按键、禁用流程和重新连接。
编辑器的普通聊天测试面板发送聊天事件,不会模拟命名 API 触发器。通过 Stream Deck 或 API 测试此触发器,以验证完整路径。