指令與 API - Social Stream Ninja

機器人指令

內建機器人指令

Social Stream Ninja 包含多個內建指令，觀眾可以在聊天中使用，你也可以透過 API 觸發。

指令	說明	如何啟用
`!joke`	隨機回覆一個極客風格的冷笑話	透過擴充功能選單開關啟用
`hi`	自動歡迎在聊天中說「hi」的人	透過擴充功能選單開關啟用
`!cycle`	啟用後，允許觀眾變更 OBS 場景	透過擴充功能選單開關啟用

注意： 只有正確設定自動回覆器，並且你有權在相應平台發佈訊息時，機器人指令才會生效。

自動回覆設定

要使自動回覆器正常運作：

確保你已登入相應平台（YouTube、Twitch 等）
確保聊天視窗可見（未最小化）
先嘗試手動傳送測試訊息，確認權限
在擴充功能選單中啟用相應指令的開關

若要隱藏觸發自動回覆時出現的藍色偵錯列，可在啟動 Chrome 時使用 --silent-debugger-extension-api 旗標。

伺服器 API

概述

Social Stream Ninja 提供強大的 API，讓你可以透過程式控制直播設定的各個方面。API 伺服器既可向你的設定傳送指令，也可監聽從整合的聊天服務傳入的訊息。

疊加畫面管理

控制精選訊息、清除疊加畫面，並調整直播內容的外觀。

Webhook 整合

接收來自 Stripe、Ko-Fi 和 Buy Me A Coffee 等第三方服務的事件。

訊息匯出

將聊天訊息匯出到檔案，或透過 webhook（POST）轉送，以實作自訂整合。

必要設定（全域設定 → 機制）：

🎮 遠端控制（StreamDeck／Bitfocus）： 啟用 「啟用擴充功能的遠端 API 控制」 （開關 1）— 連接到 頻道 1
📡 聊天監聽器（Python／Node 應用程式）： 啟用開關 1 + 「將聊天訊息傳送到 API 伺服器」 （開關 3）— 連接到 頻道 4

請參閱完整 API 文件，瞭解詳細的設定指南和程式碼範例。

API 端點與連線方式

HTTP GET/POST

https://io.socialstream.ninja/{sessionID}/{action}/{target}/{value}

適合從 Stream Deck 或自訂指令碼傳送簡單指令。

WebSocket

wss://io.socialstream.ninja:443

用於即時雙向通訊，支援自動重新連線。

如果希望保持點對點連線而不啟用 WebSocket 模式，可以使用 Social Stream Ninja WebRTC SDK。它包含 Node 和瀏覽器範例，例如 Social Stream Ninja 監聽器.

伺服器傳送事件（SSE）

https://io.socialstream.ninja/sse/{sessionID}

用於接收伺服器的單向即時更新。

頻道系統

API 使用頻道系統進行訊息路由：

	- Channel 1: Remote control commands (default for StreamDeck/Bitfocus)
	- Channel 2: Dock page output
	- Channel 3: Extension receives commands from Dock
	- Channel 4: Chat messages from Extension (use this to receive Twitch/YouTube chat!)
	- Channel 5: Waitlist/giveaway communication
	- Channels 6-9: Reserved for future use

使用所需頻道進行連線：

// To receive chat messages (listen on channel 4):
wss://io.socialstream.ninja/join/SESSION_ID/4

// To send commands (channel 1 default):
wss://io.socialstream.ninja/join/SESSION_ID

常用 API 指令

操作	說明	範例
`sendChat`	向所有已連接的聊天平台傳送訊息	`https://io.socialstream.ninja/SESSIONID/sendChat/null/Hello everyone!`
`sendEncodedChat`	向所有平台傳送 URL 編碼的訊息	`https://io.socialstream.ninja/SESSIONID/sendEncodedChat/null/Hello%20everyone%21`
`clearOverlay`	從疊加畫面中清除精選訊息	`https://io.socialstream.ninja/SESSIONID/clearOverlay`
`nextInQueue`	顯示佇列中的下一則訊息	`https://io.socialstream.ninja/SESSIONID/nextInQueue`
`autoShow`	切換訊息自動精選功能	`https://io.socialstream.ninja/SESSIONID/autoShow/toggle`
`blockUser`	封鎖某個特定平台上的使用者	`https://io.socialstream.ninja/SESSIONID/blockUser/null/{"chatname":"username","type":"twitch"}`
`extContent`	將外部內容作為聊天訊息傳送	`https://io.socialstream.ninja/SESSIONID/extContent/null/{"chatname":"User","chatmessage":"Hello"}`
`pin`	按訊息 ID 置頂停駐面板中已有的訊息，或置頂完整的訊息物件。需要 `dock.html` 在同一個工作階段中保持開啟。	`https://io.socialstream.ninja/SESSIONID/pin/null/MESSAGE_MID`
`unpin`	按訊息 ID 取消停駐面板中已有訊息的置頂。對於帶標籤的停駐面板，請使用 target 欄位／路徑區段。	`https://io.socialstream.ninja/SESSIONID/unpin/null/MESSAGE_MID`
`nextPinned`	將停駐面板中第一則置頂訊息設為精選。	`https://io.socialstream.ninja/SESSIONID/nextPinned`
`removefromwaitlist`	移除第一個有效的等候名單項目，或下列參數指定編號的有效項目： `value`	`https://io.socialstream.ninja/SESSIONID/removefromwaitlist/null/1`
`highlightwaitlist`	醒目顯示第一個有效的等候名單項目，或下列參數指定編號的有效項目： `value`	`https://io.socialstream.ninja/SESSIONID/highlightwaitlist/null/1`
`stopentries` / `startentries`	停止或恢復接收新的等候名單報名，不會清除現有名單。 `openentries` 和 `resumeentries` 是下列指令的別名： `startentries`.	`https://io.socialstream.ninja/SESSIONID/stopentries`
`selectwinner`	從等候名單／抽獎中隨機選出一個或多個獲勝者	`https://io.socialstream.ninja/SESSIONID/selectwinner/null/1`
`downloadwaitlist`	從執行中的 Social Stream 頁面／應用程式下載目前的等候名單，格式為 TSV 檔案	`https://io.socialstream.ninja/SESSIONID/downloadwaitlist`
`drawmode`	開啟／關閉抽獎模式，或在下列條件成立時切換： `value` 等於 `toggle`	`https://io.socialstream.ninja/SESSIONID/drawmode/null/toggle`
`waitlistmessage`	設定等候名單頁面顯示的等候名單或抽獎標題訊息	`https://io.socialstream.ninja/SESSIONID/waitlistmessage/null/Type%20!join%20to%20enter`
`resetwaitlist`	清空等候名單並重新開放報名	`https://io.socialstream.ninja/SESSIONID/resetwaitlist`

查看完整 API 文件

互動式 API 沙箱

使用我們的互動式沙箱試用 API，輕鬆存取所有指令和功能：

如需在 OBS 中使用更精簡的直播控制按鈕，請使用 Social Stream 控制停駐面板並遵循 OBS 設定指南.

開啟 API 沙箱

測試指令

在安全環境中試用所有 API 指令

產生程式碼

取得 HTTP、WebSocket 和 SSE 的程式碼範例

查看結果

查看指令的即時回應

建立測試

產生隨機內容的測試訊息

注意： 記得替換 SESSIONID 為你在 Social Stream Ninja 中實際使用的工作階段 ID！

StreamDeck 與 Companion

StreamDeck 整合

Social Stream Ninja 透過多種方式與 StreamDeck 整合：原生 HTTP 動作和 Bitfocus Companion 整合。

HTTP／API 方式

使用 StreamDeck 的「Website」動作，並啟用「GET request in background」，即可直接向 API 傳送指令。

Bitfocus Companion

原生整合，提供預設動作、即時回饋，以及用於動態內容的變數。

Companion 整合

Bitfocus Companion 可透過 WebSocket 或 HTTP API 對 Social Stream Ninja 進行強大的控制。

操作	說明	API 方式
清除精選訊息	從疊加畫面中移除目前的精選訊息	WebSocket/HTTP
佇列中的下一則	顯示下一則排隊的訊息	WebSocket/HTTP
切換自動顯示	啟用／停用自動精選訊息	WebSocket/HTTP
傳送聊天訊息	向所有已連接的平台傳送訊息	WebSocket/HTTP

動態變數

featured_message - 目前的精選訊息文字
featured_username - 目前精選使用者的使用者名稱
queue_size - 佇列中的訊息數量

設定資源

取得 Companion 模組文件

AI 整合

AI 聊天機器人模式

Social Stream Ninja 提供全面的 AI 整合，透過 AI 聊天回覆、內容審核等功能增強直播。可根據需要選擇本機或雲端 AI 供應商。

自動聊天回覆

讓 AI 自動與你的觀眾互動、回答問題，即使你專注於自己的內容，也能保持對話活躍。

內容審核

使用 AI 識別可能有害的訊息，並按你的偏好自動處理，輔助管理聊天。可選擇不封鎖模式或嚴格封鎖模式。

RAG 搜尋

檢索增強生成使 AI 能搜尋你的自訂知識庫，提供準確且貼合你內容的回答。

多個機器人執行個體

執行不同的機器人執行個體，滿足不同用途：公開聊天機器人、私人一對一機器人、審查機器人，甚至能看能聽的多模態 AI 搭檔。

支援的 AI 供應商

Social Stream Ninja 支援多種 AI 供應商，從完全在本機執行的瀏覽器／執行階段模型到託管 API：

Ollama（原生本機 API）

免費、注重隱私的自行託管 AI 模型，透過 Ollama 本身的 API 在你的電腦上執行。

本機 Gemma 4

先將模型檔案鏡像到自己的資源伺服器，再在瀏覽器中執行 Gemma 4；SSN 的 largefiles 伺服器目前不包含 Gemma 資源。

本機 Qwen 3.5

使用自行託管的模型檔案在瀏覽器中執行 Qwen 3.5，在本機產生私密回覆。

ChatGPT / OpenAI

OpenAI API，包括現代聊天和即時語音模型。

Google Gemini

Google Gemini 模型，包括目前的 Gemini 2.5 文字和即時多模態選項。

DeepSeek

針對對話任務最佳化、高效且經濟的 AI 模型。

xAI (Grok)

xAI Grok API，包括使用暫時性用戶端密鑰時的即時語音工作階段。

AWS Bedrock

來自不同供應商的企業級 AI 模型，包括 Claude 和 Llama。

OpenRouter

透過統一的 API 介面存取多種 AI 模型。

Groq

相容於 OpenAI 的低延遲聊天推論，實現快速的對話回覆。

自訂 API（相容於 OpenAI）

連接到 llama.cpp、LM Studio、vLLM 或其他任何相容於 OpenAI 的端點。

注意： Ollama 使用本身的原生 API。對於 llama.cpp、LM Studio、vLLM 或其他相容於 OpenAI 的伺服器，請選擇 自訂 API.

文字轉語音整合

Social Stream Ninja 為機器人訊息和精選聊天內容提供全面的 TTS 支援：

系統 TTS

免費的內建 TTS，使用作業系統的語音合成器。

Kokoro

免費的本機 TTS，使用 WebGPU／CPU 執行，適合注重隱私的使用者。

Kitten TTS

輕量級的瀏覽器 TTS，下載小型模型後可在本機產生語音。

ElevenLabs

優質語音合成，提供自然且可自訂的聲音。

Google Cloud TTS

高品質聲音，提供豐富的語言和自訂選項。

Gemini（預覽版 TTS）

Google 的預覽版神經語音模型，可選擇聲音和語言。

Speechify

由 AI 驅動的文字轉語音，具備自然的聲音轉換能力。

OpenAI TTS

OpenAI 語音合成，可選擇聲音、模型，並可使用相容端點。

注意： TTS 功能需要在 OBS 中開啟相應的疊加畫面頁面。不同 TTS 供應商有不同的聲音選項、延遲，以及價格或硬體需求。

機器人執行個體與疊加畫面

Social Stream Ninja 為不同使用情境提供多個機器人執行個體：

機器人類型	URL	說明
主要聊天機器人	`/bot.html`	主要機器人疊加畫面，可選 TTS 和公開聊天回覆
私人聊天介面	`/chatbot.html`	專用的一對一機器人頁面，不與主要機器人共用 RAG 資料集或聊天記錄
審查機器人	（在背景執行）	自動篩選、清理或封鎖傳入訊息
AI 搭檔	`/cohost.html`	能夠查看螢幕、聽取音訊並互動的多模態 AI

設定 AI 整合

按照以下步驟，在目前選單中設定 AI 整合：

1

選擇並連接 LLM 供應商

在下列位置選擇供應商： 設定 LLM 服務提供者 ，並填寫對應欄位：

Ollama： 在本機安裝，並按需設定端點
本機 Gemma / 本機 Qwen： 使用託管的瀏覽器模型資源，並可覆寫模型資料夾；Qwen 可使用 SSN largefiles，Gemma 則需要你自己的鏡像資料夾
ChatGPT、Gemini、DeepSeek、xAI、Groq、OpenRouter、Bedrock： 新增 API 金鑰和偏好模型
自訂 API： 輸入相容於 OpenAI 的端點、模型 ID，以及選用的 API 金鑰

2

測試所選聊天機器人

使用內建的 測試所選聊天機器人 按鈕，在開播前驗證供應商、模型和憑證。

3

設定機器人行為

自訂機器人在聊天中的行為：

啟用 LLM AI 聊天機器人
設定機器人名稱、觸發詞和回覆頻率限制
選擇將回覆傳回聊天，還是僅傳送到機器人疊加畫面頁面
新增自訂指示，指定語氣、角色和管理規則

4

啟用選用的附加功能

開啟所需的機器人相關功能：

為機器人回覆啟用 TTS，並選擇供應商
為以下頁面選擇固定時間、按訊息長度或 TTS 後自動隱藏的行為： /bot.html；使用 clearBotOverlay 進行手動清除
啟用 RAG 並上傳文件，讓回答參考相關知識
啟用審查機器人進行內容審核或嚴格封鎖
開啟 /bot.html, /chatbot.html，或 /cohost.html ，按需在 OBS 或瀏覽器中使用

詳細文件

完整設定說明和更深入的 TTS 內容，請參閱以下指南：

AI 聊天機器人設定指南本機 AI TTS 指南用於自動回覆的機器人帳號 Ollama 官方下載

MIDI 與快速鍵控制

MIDI 整合

使用 MIDI 控制器、鍵盤快捷鍵或搭配 MIDI 外掛的 StreamDeck 控制 Social Stream Ninja。

設定需求

在擴充功能設定中啟用 MIDI 支援
安裝虛擬 MIDI 回送裝置（例如 loopMIDI）
設定 MIDI 控制器或 StreamDeck MIDI 外掛

CC 編號	值	操作	說明
102	1	向聊天傳送「1」	快速回應
102	2	向聊天傳送「LUL」	表情回應
102	3	講個笑話	觸發機器人回覆
102	4	清除疊加畫面	移除精選訊息

提示： MIDI 控制最適合實體控制器，也可透過虛擬 MIDI 裝置觸發。

快速鍵支援

使用鍵盤快速鍵快速存取常用功能。

可在選單設定中設定快速鍵；當瀏覽器取得焦點或使用應用程式時，快速鍵可在系統範圍內生效。

Webhook 整合

贊助服務

Social Stream Ninja 可以透過 webhook 接收第三方服務的贊助和事件；以下列出幾個熱門服務：

Stripe

直接透過你的 Stripe 帳號處理信用卡贊助。

在此建立付款連結： stripe.com
在 Stripe Dashboard 中，前往 Developers → Webhooks
新增端點： https://io.socialstream.ninja/SESSIONID/stripe
選擇事件 checkout.session.completed
新增 &server 到停駐面板 URL

Ko-Fi

接受支持者請你喝咖啡的贊助。

登入你的 Ko-Fi 帳號
前往 Webhook 設定
新增 https://io.socialstream.ninja/SESSIONID/kofi 作為 webhook URL
新增 &server 到停駐面板 URL
使用「傳送單則贊助測試」按鈕進行測試

Buy Me A Coffee

透過熱門的 Buy Me A Coffee 平台接受贊助。

登入你的 Buy Me A Coffee 帳號
前往 webhook 設定
新增 https://io.socialstream.ninja/SESSIONID/bmac 作為 webhook URL
新增 &server 到停駐面板 URL，以接收事件
支援贊助和會員事件

安全提示： 請保密你的工作階段 ID，因為任何持有它的人都能向疊加畫面傳送虛假贊助。應將 webhook URL 視為敏感資訊。

外部服務整合

Social Stream Ninja 也可以向第三方服務傳送資料：

服務	URL 參數	說明
Singular Live	`&singular=IDENTIFIER`	將選定訊息傳送到 Singular Live，用於精選訊息疊加畫面
H2R	`&h2r=IDENTIFIER`	將選定訊息傳送到本機 H2R 伺服器
通用 POST	`&postserver=URL`	透過 POST 將選定訊息傳送到自訂端點
通用 PUT	`&putserver=URL`	透過 PUT 將選定訊息傳送到自訂端點

這些參數應加入停駐面板頁面的 URL 中。

自訂指令碼

自訂 JavaScript

你可以透過自訂 JavaScript 程式碼，建立自己的指令和功能：

使用 custom.js

重新命名 custom_sample.js 為檔名 custom.js
編輯檔案以新增自訂功能
在本機開啟 dock.html 檔案以載入 custom.js

此方法可實作複雜的自訂功能和觸發器。

自訂疊加畫面

建立自訂疊加畫面

你可以從頭建立完全自訂的聊天疊加畫面，配合直播獨特的風格和功能。Social Stream Ninja 提供彈性的基礎，供你繼續擴充。

從範本開始

先使用我們的疊加畫面範例範本，瞭解基礎知識：

// View the sample overlay
https://socialstream.ninja/sampleoverlay?session=SESSIONID

這個最精簡的範本只包含疊加畫面正常運作所需的基本程式碼。

查看疊加畫面範例

可自訂的主要功能

在精選訊息與顯示全部訊息之間切換
使用 CSS 自訂外觀
為新訊息新增自訂動畫
實作自己的訊息篩選邏輯
使用 JavaScript 新增互動元素

實作步驟

下載疊加畫面範例 HTML 檔案
編輯 HTML 以實作自訂版面配置
自訂 CSS 以取得所需外觀
按需修改 JavaScript，實作自訂行為
將檔案儲存在本機，作為 OBS 瀏覽器來源使用

計時器 API

遠端控制： `timer.html`

計時器頁面刻意保持精簡：一個計時器、選用的操作員控制項、警告狀態、超時計時和幾種視覺樣式。

實用動作包括 starttimer, pausetimer, resettimer, timeradd, timersubtract，以及 settimer.

{
  "action": "settimer",
  "value": {
    "seconds": 300,
    "label": "Interview",
    "mode": "countdown",
    "style": "stage",
    "warnSeconds": 60,
    "dangerSeconds": 15
  }
}

如需查詢目前計時器狀態，請使用 gettimerstate 並附上回呼權杖。

{ "action": "gettimerstate", "get": "timer-state-1" }

開啟頁面時使用 timer.html?session=YOUR_SESSION&server ，即可直接透過 API 伺服器控制它。