Polecenia i API — Social Stream Ninja

Polecenia bota

Wbudowane polecenia bota

Social Stream Ninja zawiera kilka wbudowanych poleceń, których widzowie mogą używać na czacie lub które możesz wywoływać przez API.

Polecenie	Opis	Jak włączyć
`!joke`	Odpowiada losowym sucharem o tematyce technologicznej	Włącz przełącznikiem w menu rozszerzenia
`hi`	Automatycznie wita każdego, kto napisze „hi” na czacie	Włącz przełącznikiem w menu rozszerzenia
`!cycle`	Po włączeniu pozwala widzom zmieniać sceny OBS	Włącz przełącznikiem w menu rozszerzenia

Uwaga: Polecenia bota działają tylko po poprawnym skonfigurowaniu automatycznych odpowiedzi i uzyskaniu uprawnień do publikowania na odpowiednich platformach.

Konfiguracja automatycznych odpowiedzi

Aby automatyczne odpowiedzi działały poprawnie:

Upewnij się, że jesteś zalogowany na platformie (YouTube, Twitch itd.)
Upewnij się, że okno czatu jest widoczne, a nie zminimalizowane
Najpierw spróbuj ręcznie wysłać wiadomość testową, aby potwierdzić uprawnienia
Włącz przełączniki odpowiednich poleceń w menu rozszerzenia

Jeśli przy automatycznych odpowiedziach pojawia się niebieski pasek debugowania, możesz go ukryć, uruchamiając Chrome z flagą --silent-debugger-extension-api .

API serwera

Przegląd

Social Stream Ninja oferuje rozbudowane API do programowego sterowania każdym elementem konfiguracji transmisji. Serwer API może zarówno wysyłać polecenia do konfiguracji, jak i odbierać przychodzące wiadomości z połączonych usług czatu.

Zarządzanie nakładkami

Steruj wyróżnionymi wiadomościami, czyść nakładki i zmieniaj wygląd treści podczas transmisji.

Integracja webhooków

Odbieraj wydarzenia z usług zewnętrznych, takich jak Stripe, Ko-Fi i Buy Me A Coffee.

Eksport wiadomości

Eksportuj wiadomości czatu do pliku lub przekazuj przez webhook (POST) do własnych integracji.

Wymagane ustawienia (Global settings → Mechanics):

🎮 Zdalne sterowanie (StreamDeck/Bitfocus): Włącz „Włącz zdalne sterowanie rozszerzeniem przez API” (Enable remote API control of extension) (Przełącznik 1) — połącz z kanałem 1
📡 Odbiornik czatu (aplikacje Python/Node): Włącz przełącznik 1 + „Wysyłaj wiadomości czatu do serwera API” (Send chat messages to API server) (Przełącznik 3) — połącz z kanałem 4

Zobacz pełną dokumentację API aby uzyskać szczegółowe instrukcje i przykłady kodu.

Adresy API i metody połączenia

HTTP GET/POST

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

Idealne do prostych poleceń ze Stream Deck lub własnych skryptów.

WebSocket

wss://io.socialstream.ninja:443

Do dwukierunkowej komunikacji w czasie rzeczywistym z automatycznym ponownym łączeniem.

Jeśli wolisz połączenia peer-to-peer bez trybu WebSocket, możesz użyć Social Stream Ninja WebRTC SDK. Zawiera przykłady dla Node i przeglądarki, takie jak Odbiornik Social Stream Ninja.

Server-Sent Events

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

Do jednokierunkowych aktualizacji z serwera w czasie rzeczywistym.

System kanałów

API używa systemu kanałów do kierowania wiadomości:

	- 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

Połącz z wybranym kanałem:

// 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

Typowe polecenia API

Działanie	Opis	Przykład
`sendChat`	Wysyła wiadomość na wszystkie połączone platformy czatu	`https://io.socialstream.ninja/SESSIONID/sendChat/null/Hello everyone!`
`sendEncodedChat`	Wysyła wiadomość zakodowaną jako URL na wszystkie platformy	`https://io.socialstream.ninja/SESSIONID/sendEncodedChat/null/Hello%20everyone%21`
`clearOverlay`	Usuwa wyróżnioną wiadomość z nakładki	`https://io.socialstream.ninja/SESSIONID/clearOverlay`
`nextInQueue`	Wyświetla następną wiadomość w kolejce	`https://io.socialstream.ninja/SESSIONID/nextInQueue`
`autoShow`	Przełącza automatyczne wyróżnianie wiadomości	`https://io.socialstream.ninja/SESSIONID/autoShow/toggle`
`blockUser`	Blokuje użytkownika na określonej platformie	`https://io.socialstream.ninja/SESSIONID/blockUser/null/{"chatname":"username","type":"twitch"}`
`extContent`	Wysyła zewnętrzną treść jako wiadomość czatu	`https://io.socialstream.ninja/SESSIONID/extContent/null/{"chatname":"User","chatmessage":"Hello"}`
`pin`	Przypina istniejącą wiadomość doku według ID albo pełny obiekt wiadomości. Wymaga `dock.html` otwarte w tej samej sesji.	`https://io.socialstream.ninja/SESSIONID/pin/null/MESSAGE_MID`
`unpin`	Odpina istniejącą wiadomość doku według ID. Dla doku z etykietą użyj pola lub segmentu ścieżki target.	`https://io.socialstream.ninja/SESSIONID/unpin/null/MESSAGE_MID`
`nextPinned`	Wyróżnia pierwszą przypiętą wiadomość doku.	`https://io.socialstream.ninja/SESSIONID/nextPinned`
`removefromwaitlist`	Usuwa pierwszą aktywną pozycję listy oczekujących lub aktywną pozycję o numerze w `value`	`https://io.socialstream.ninja/SESSIONID/removefromwaitlist/null/1`
`highlightwaitlist`	Wyróżnia pierwszą aktywną pozycję listy oczekujących lub aktywną pozycję o numerze w `value`	`https://io.socialstream.ninja/SESSIONID/highlightwaitlist/null/1`
`stopentries` / `startentries`	Wstrzymuje lub wznawia nowe zapisy na listę oczekujących bez czyszczenia obecnej listy. `openentries` i `resumeentries` są aliasami `startentries`.	`https://io.socialstream.ninja/SESSIONID/stopentries`
`selectwinner`	Losuje jednego lub kilku zwycięzców z listy oczekujących/losowania	`https://io.socialstream.ninja/SESSIONID/selectwinner/null/1`
`downloadwaitlist`	Pobiera bieżącą listę oczekujących jako plik TSV z uruchomionej strony/aplikacji Social Stream	`https://io.socialstream.ninja/SESSIONID/downloadwaitlist`
`drawmode`	Włącza/wyłącza tryb losowania lub przełącza go, gdy `value` równa się `toggle`	`https://io.socialstream.ninja/SESSIONID/drawmode/null/toggle`
`waitlistmessage`	Ustawia tytuł listy oczekujących lub losowania pokazywany na stronie kolejki	`https://io.socialstream.ninja/SESSIONID/waitlistmessage/null/Type%20!join%20to%20enter`
`resetwaitlist`	Czyści listę oczekujących i ponownie otwiera zapisy	`https://io.socialstream.ninja/SESSIONID/resetwaitlist`

Zobacz pełną dokumentację API

Interaktywna piaskownica API

Wypróbuj API w interaktywnej piaskownicy z łatwym dostępem do wszystkich poleceń i funkcji:

Jeśli potrzebujesz mniejszego zestawu przycisków do realizacji transmisji w OBS, użyj Doku sterowania Social Stream i postępuj zgodnie z poradnikiem konfiguracji OBS.

Otwórz piaskownicę API

Testuj polecenia

Wypróbuj wszystkie polecenia API w bezpiecznym środowisku

Generuj kod

Pobierz przykłady kodu dla HTTP, WebSocket i SSE

Zobacz wyniki

Obserwuj odpowiedzi na polecenia w czasie rzeczywistym

Utwórz testy

Generuj wiadomości testowe z losową treścią

Uwaga: Pamiętaj, aby zastąpić SESSIONID swoim rzeczywistym ID sesji z Social Stream Ninja!

StreamDeck i Companion

Integracja StreamDeck

Social Stream Ninja integruje się ze StreamDeck na kilka sposobów: przez natywne działania HTTP i Bitfocus Companion.

Metoda HTTP/API

Użyj działania „Website” w StreamDeck z włączonym „GET request in background”, aby wysyłać polecenia bezpośrednio do API.

Bitfocus Companion

Natywna integracja z gotowymi działaniami, informacją zwrotną na żywo i zmiennymi do treści dynamicznych.

Integracja Companion

Bitfocus Companion zapewnia rozbudowane sterowanie Social Stream Ninja przez API WebSocket lub HTTP.

Działanie	Opis	Metoda API
Wyczyść wyróżnioną wiadomość	Usuwa aktualnie wyróżnioną wiadomość z nakładki	WebSocket/HTTP
Następna w kolejce	Wyświetla kolejną oczekującą wiadomość	WebSocket/HTTP
Przełącz automatyczny pokaz	Włącza/wyłącza automatyczne wyróżnianie wiadomości	WebSocket/HTTP
Wyślij wiadomość czatu	Wysyła wiadomość na wszystkie połączone platformy	WebSocket/HTTP

Zmienne dynamiczne

featured_message — tekst bieżącej wyróżnionej wiadomości
featured_username — nazwa autora bieżącej wyróżnionej wiadomości
queue_size — liczba wiadomości w kolejce

Materiały konfiguracyjne

Pobierz Companion Dokumentacja modułu

Integracja AI

Tryb bota czatu AI

Social Stream Ninja oferuje szeroką integrację AI, wzbogacając transmisje o odpowiedzi czatu, moderację i inne funkcje. Wybierz lokalnego lub chmurowego dostawcę AI zgodnie z potrzebami.

Automatyczne odpowiedzi na czacie

Pozwól AI automatycznie angażować widzów, odpowiadać na pytania i podtrzymywać rozmowę, gdy skupiasz się na swoich treściach.

Moderacja treści

Używaj AI do moderacji czatu: rozpoznawania potencjalnie szkodliwych wiadomości i automatycznej obsługi według twoich preferencji. Wybierz tryb nieblokujący lub ścisłego blokowania.

Wyszukiwanie RAG

Generowanie wspomagane wyszukiwaniem pozwala AI przeszukiwać własną bazę wiedzy i udzielać dokładnych odpowiedzi dotyczących twoich treści.

Wiele instancji botów

Uruchamiaj różne instancje botów: publicznego bota czatu, prywatnego bota sam na sam, bota cenzurującego, a nawet multimodalnego współprowadzącego AI, który widzi i słyszy.

Obsługiwani dostawcy AI

Social Stream Ninja obsługuje wielu dostawców AI — od w pełni lokalnych modeli przeglądarkowych i wykonawczych po hostowane API:

Ollama (natywne lokalne API)

Darmowe, nastawione na prywatność modele AI działające na twoim komputerze przez własne API Ollama.

Local Gemma 4

Uruchom Gemma 4 w przeglądarce po skopiowaniu plików modelu na własny serwer zasobów; host SSN largefiles obecnie nie zawiera plików Gemma.

Local Qwen 3.5

Uruchom Qwen 3.5 w przeglądarce z własnych hostowanych plików modelu, aby uzyskać lokalne, prywatne odpowiedzi.

ChatGPT / OpenAI

API OpenAI, w tym nowoczesne modele czatu i głosu w czasie rzeczywistym.

Google Gemini

Modele Google Gemini, w tym aktualne opcje tekstowe Gemini 2.5 i multimodalne na żywo.

DeepSeek

Wydajne, ekonomiczne modele AI zoptymalizowane do rozmów.

xAI (Grok)

API xAI Grok, w tym sesje głosowe na żywo przy użyciu krótkotrwałych sekretów klienta.

AWS Bedrock

Modele AI klasy biznesowej różnych dostawców, w tym Claude i Llama.

OpenRouter

Dostęp do wielu modeli AI przez wspólny interfejs API.

Groq

Szybkie generowanie odpowiedzi czatu zgodne z OpenAI o niskim opóźnieniu.

Własne API (zgodne z OpenAI)

Połącz z llama.cpp, LM Studio, vLLM lub inną usługą zgodną z OpenAI.

Uwaga: Ollama używa własnego natywnego API. Dla llama.cpp, LM Studio, vLLM i innych serwerów zgodnych z OpenAI wybierz Własne API.

Integracja syntezy mowy

Social Stream Ninja zapewnia rozbudowaną obsługę TTS wiadomości bota i wyróżnionego czatu:

Systemowy TTS

Darmowy wbudowany TTS korzystający z syntezatora głosu systemu operacyjnego.

Kokoro

Darmowy lokalny TTS wykorzystujący WebGPU/CPU dla osób dbających o prywatność.

Kitten TTS

Lekki TTS przeglądarkowy pobierający mały model do lokalnego generowania głosu.

ElevenLabs

Płatna synteza mowy z naturalnymi, dostosowywanymi głosami.

Google Cloud TTS

Wysokiej jakości głosy z bogatym wyborem języków i opcji dostosowania.

Gemini (próbny TTS)

Próbne neuronowe modele głosu Google z wyborem głosu i języka.

Speechify

Synteza mowy AI z możliwościami naturalnej konwersji głosu.

OpenAI TTS

Synteza mowy OpenAI z wyborem głosów, modeli i opcjonalnych zgodnych usług.

Uwaga: TTS wymaga otwarcia właściwej strony nakładki w OBS. Każdy dostawca oferuje inne głosy, opóźnienia, ceny lub wymagania sprzętowe.

Instancje botów i nakładki

Social Stream Ninja udostępnia kilka instancji botów do różnych zastosowań:

Typ bota	URL	Opis
Główny bot czatu	`/bot.html`	Nakładka głównego bota z opcjonalnym TTS i publicznymi odpowiedziami na czacie
Prywatny interfejs czatu	`/chatbot.html`	Osobna strona bota do rozmowy sam na sam, bez współdzielenia zbioru RAG ani historii czatu głównego bota
Bot cenzurujący	(działa w tle)	Automatycznie filtruje, oczyszcza lub blokuje przychodzące wiadomości
Współprowadzący AI	`/cohost.html`	Multimodalne AI, które widzi ekran, słyszy dźwięk i reaguje

Konfiguracja integracji AI

Aby skonfigurować integrację AI w obecnym menu, wykonaj te kroki:

1

Wybierz i połącz dostawcę LLM

Wybierz dostawcę w sekcji Skonfiguruj dostawcę usługi LLM i uzupełnij odpowiednie pola:

Ollama: Zainstaluj lokalnie i w razie potrzeby ustaw adres usługi
Local Gemma / Local Qwen: Użyj hostowanych plików modelu przeglądarkowego i opcjonalnego zastąpienia folderu; Qwen może korzystać z SSN largefiles, a Gemma wymaga własnej kopii folderu
ChatGPT, Gemini, DeepSeek, xAI, Groq, OpenRouter, Bedrock: Dodaj klucz API i preferowany model
Własne API: Wpisz adres zgodny z OpenAI, identyfikator modelu i opcjonalny klucz API

2

Przetestuj wybranego bota czatu

Użyj wbudowanego przycisku Przetestuj wybranego bota czatu aby przed transmisją sprawdzić dostawcę, model i dane uwierzytelniające.

3

Skonfiguruj zachowanie bota

Dostosuj zachowanie bota na czacie:

Włącz bota czatu AI LLM
Ustaw nazwę bota, słowa wyzwalające i limit częstotliwości odpowiedzi
Wybierz, czy odpowiedzi mają wracać na czat, czy trafiać tylko na stronę nakładki bota
Dodaj własne instrukcje dotyczące tonu, roli i zasad moderacji

4

Włącz opcjonalne dodatki

Włącz potrzebne funkcje wokół bota:

Włącz TTS odpowiedzi bota i wybierz dostawcę
Wybierz stały czas, czas zależny od długości wiadomości lub ukrywanie po TTS dla /bot.html; użyj clearBotOverlay do ręcznego czyszczenia
Włącz RAG i prześlij dokumenty, aby odpowiedzi korzystały z wiedzy
Włącz bota cenzurującego do moderacji lub ścisłego blokowania
Otwórz /bot.html, /chatbot.html lub /cohost.html w OBS lub przeglądarce według potrzeb

Szczegółowa dokumentacja

Pełne instrukcje konfiguracji i szczegóły TTS znajdziesz w poradnikach:

Poradnik konfiguracji bota czatu AI Poradnik lokalnego TTS AI Konta botów do automatycznych odpowiedzi Oficjalne pobieranie Ollama

Sterowanie MIDI i skrótami

Integracja MIDI

Steruj Social Stream Ninja za pomocą kontrolerów MIDI, skrótów klawiaturowych lub StreamDeck z wtyczkami MIDI.

Wymagania konfiguracji

Włącz obsługę MIDI w ustawieniach rozszerzenia
Zainstaluj wirtualne urządzenie pętli MIDI (np. loopMIDI)
Skonfiguruj kontroler MIDI lub wtyczkę MIDI StreamDeck

Numer CC	Wartość	Działanie	Uwagi
102	1	Wyślij „1” na czat	Szybka reakcja
102	2	Wyślij „LUL” na czat	Reakcja emotką
102	3	Opowiedz dowcip	Wywołuje odpowiedź bota
102	4	Wyczyść nakładkę	Usuwa wyróżnioną wiadomość

Wskazówka: Sterowanie MIDI najlepiej działa z fizycznymi kontrolerami, ale można je też wywoływać przez urządzenia wirtualne.

Obsługa skrótów klawiaturowych

Używaj skrótów klawiaturowych do szybkiego dostępu do typowych funkcji.

Skróty można skonfigurować w ustawieniach menu; działają w całym systemie, gdy przeglądarka ma fokus lub używana jest aplikacja.

Integracja webhooków

Usługi wpłat

Social Stream Ninja może odbierać wpłaty i wydarzenia z usług zewnętrznych przez webhooki; poniżej kilka popularnych:

Stripe

Przyjmuj wpłaty kartą bezpośrednio na konto Stripe.

Utwórz link płatności w stripe.com
W panelu Stripe przejdź do Developers → Webhooks
Dodaj adres usługi: https://io.socialstream.ninja/SESSIONID/stripe
Wybierz wydarzenie checkout.session.completed
Dodaj &server do URL doku

Ko-Fi

Przyjmuj wpłaty na kawę od wspierających.

Zaloguj się na konto Ko-Fi
Otwórz Ustawienia webhooków
Dodaj https://io.socialstream.ninja/SESSIONID/kofi jako URL webhooka
Dodaj &server do URL doku
Przetestuj przyciskiem „Send Single Donation Test”

Buy Me A Coffee

Przyjmuj wpłaty przez popularną platformę Buy Me A Coffee.

Zaloguj się na konto Buy Me A Coffee
Przejdź do ustawień webhooków
Dodaj https://io.socialstream.ninja/SESSIONID/bmac jako URL webhooka
Dodaj &server do URL doku, aby odbierać wydarzenia
Obsługiwane są zarówno wpłaty, jak i wydarzenia członkostwa

Uwaga o bezpieczeństwie: Zachowaj ID sesji w tajemnicy, ponieważ każda osoba, która je zna, może wysyłać fałszywe wpłaty do nakładki. URL webhooka należy traktować jako poufną informację.

Integracja usług zewnętrznych

Social Stream Ninja może też wysyłać dane do usług zewnętrznych:

Usługa	Parametr URL	Opis
Singular Live	`&singular=IDENTIFIER`	Wysyła wybrane wiadomości do Singular Live do nakładki wyróżnionych wiadomości
H2R	`&h2r=IDENTIFIER`	Wysyła wybrane wiadomości do lokalnego serwera H2R
Ogólny POST	`&postserver=URL`	Wysyła wybrane wiadomości do własnej usługi przez POST
Ogólny PUT	`&putserver=URL`	Wysyła wybrane wiadomości do własnej usługi przez PUT

Te parametry należy dodać do URL strony doku.

Własne skrypty

Własny JavaScript

Możesz tworzyć własne polecenia i funkcje, dostosowując kod JavaScript:

Korzystanie z custom.js

Zmień nazwę custom_sample.js na custom.js
Edytuj plik, aby dodać własne funkcje
Otwórz lokalnie plik dock.html, aby załadować custom.js

Ta metoda pozwala na złożone dostosowania i wyzwalacze.

Własne nakładki

Tworzenie własnych nakładek

Możesz od podstaw tworzyć własne nakładki czatu dopasowane do stylu i funkcji transmisji. Social Stream Ninja zapewnia elastyczną podstawę do rozbudowy.

Zacznij od szablonu

Zacznij od przykładowego szablonu nakładki, aby poznać podstawy:

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

Ten minimalny szablon zawiera tylko kod niezbędny do działania nakładki.

Zobacz przykładową nakładkę

Najważniejsze elementy do dostosowania

Przełącz między wyróżnionymi wiadomościami a wszystkimi wiadomościami
Dostosuj wygląd za pomocą CSS
Dodaj własne animacje nowych wiadomości
Zaimplementuj własne filtrowanie wiadomości
Dodaj elementy interaktywne za pomocą JavaScript

Kroki wdrożenia

Pobierz przykładowy plik HTML nakładki
Edytuj HTML, aby stworzyć własny układ
Dostosuj CSS do oczekiwanego wyglądu
W razie potrzeby zmodyfikuj JavaScript, aby uzyskać własne zachowanie
Zapisz plik lokalnie, aby użyć go w OBS jako źródła przeglądarki

API timera

Zdalne sterowanie `timer.html`

Strona timera ma celowo wąski zakres: jeden timer, opcjonalne sterowanie operatora, stany ostrzeżeń, czas po terminie i kilka stylów wizualnych.

Przydatne działania obejmują starttimer, pausetimer, resettimer, timeradd, timersubtract i settimer.

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

Aby odczytać bieżący stan timera, użyj gettimerstate z tokenem odpowiedzi zwrotnej.

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

Użyj strony z timer.html?session=YOUR_SESSION&server jeśli chcesz sterować nim bezpośrednio przez serwer API.