Comandi e API - Social Stream Ninja

Comandi dei bot

Comandi dei bot integrati

Social Stream Ninja include diversi comandi integrati che gli spettatori possono usare nella chat o che puoi attivare tramite API.

Comando	Descrizione	Come attivare
`!joke`	Risponde con una battuta nerd casuale	Attiva tramite l'interruttore nel menu dell'estensione
`hi`	Dà automaticamente il benvenuto a chi scrive «hi» in chat	Attiva tramite l'interruttore nel menu dell'estensione
`!cycle`	Quando attivo, permette agli spettatori di cambiare le scene OBS	Attiva tramite l'interruttore nel menu dell'estensione

Nota: I comandi dei bot funzionano solo quando il risponditore automatico è configurato correttamente e hai il permesso di pubblicare messaggi nelle rispettive piattaforme.

Configurazione delle risposte automatiche

Per il corretto funzionamento del risponditore automatico:

Assicurati di aver effettuato l'accesso alla piattaforma (YouTube, Twitch ecc.)
Assicurati che la finestra della chat sia visibile, non ridotta a icona
Prima prova a inviare manualmente un messaggio per verificare i permessi
Attiva i singoli comandi nel menu dell'estensione

Se quando si attivano le risposte automatiche appare una barra blu di debug, puoi nasconderla avviando Chrome con il flag --silent-debugger-extension-api .

API del server

Panoramica

Social Stream Ninja offre un'API potente che permette di controllare via codice ogni aspetto della configurazione della diretta. Il server API può sia inviare comandi alla tua configurazione sia ascoltare i messaggi in arrivo dai servizi di chat riuniti.

Gestione degli overlay

Controlla i messaggi in evidenza, cancella gli overlay e modifica l'aspetto dei contenuti nella diretta.

Integrazione webhook

Ricevi eventi da servizi esterni come Stripe, Ko-Fi e Buy Me A Coffee.

Esportazione dei messaggi

Esporta i messaggi della chat in un file o inoltrali tramite webhook (POST) per integrazioni personalizzate.

Impostazioni necessarie (Global settings → Mechanics):

🎮 Controllo remoto (StreamDeck/Bitfocus): Attiva «Attiva il controllo API remoto dell'estensione» (Enable remote API control of extension) (Interruttore 1) — Collegati a canale 1
📡 Listener della chat (app Python/Node): Attiva l'interruttore 1 + «Invia i messaggi della chat al server API» (Send chat messages to API server) (Interruttore 3) — Collegati a canale 4

Consulta documentazione API completa per guide dettagliate alla configurazione ed esempi di codice.

Endpoint API e metodi di connessione

HTTP GET/POST

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

Ideale per comandi semplici da Stream Deck o script personalizzati.

WebSocket

wss://io.socialstream.ninja:443

Per comunicazioni bidirezionali in tempo reale con riconnessione automatica.

Se preferisci mantenere le connessioni peer-to-peer senza attivare la modalità WebSocket, puoi usare l'SDK WebRTC di Social Stream Ninja. Include esempi per Node e browser, come Listener Social Stream Ninja.

Server-Sent Events

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

Per aggiornamenti in tempo reale unidirezionali dal server.

Sistema di canali

L'API usa un sistema di canali per l'instradamento dei messaggi:

	- 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

Collegati al canale desiderato:

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

Comandi API comuni

Azione	Descrizione	Esempio
`sendChat`	Invia un messaggio a tutte le piattaforme di chat connesse	`https://io.socialstream.ninja/SESSIONID/sendChat/null/Hello everyone!`
`sendEncodedChat`	Invia a tutte le piattaforme un messaggio codificato per URL	`https://io.socialstream.ninja/SESSIONID/sendEncodedChat/null/Hello%20everyone%21`
`clearOverlay`	Rimuove il messaggio in evidenza dall'overlay	`https://io.socialstream.ninja/SESSIONID/clearOverlay`
`nextInQueue`	Mostra il messaggio successivo nella coda	`https://io.socialstream.ninja/SESSIONID/nextInQueue`
`autoShow`	Attiva o disattiva la messa in evidenza automatica dei messaggi	`https://io.socialstream.ninja/SESSIONID/autoShow/toggle`
`blockUser`	Blocca un utente di una piattaforma specifica	`https://io.socialstream.ninja/SESSIONID/blockUser/null/{"chatname":"username","type":"twitch"}`
`extContent`	Invia contenuto esterno come messaggio di chat	`https://io.socialstream.ninja/SESSIONID/extContent/null/{"chatname":"User","chatmessage":"Hello"}`
`pin`	Fissa un messaggio esistente nel dock tramite il suo ID oppure un oggetto messaggio completo. Richiede `dock.html` aperto nella stessa sessione.	`https://io.socialstream.ninja/SESSIONID/pin/null/MESSAGE_MID`
`unpin`	Sblocca un messaggio fissato nel dock tramite il suo ID. Per un dock con etichetta, usa il campo o segmento di percorso target.	`https://io.socialstream.ninja/SESSIONID/unpin/null/MESSAGE_MID`
`nextPinned`	Mette in evidenza il primo messaggio fissato nel dock.	`https://io.socialstream.ninja/SESSIONID/nextPinned`
`removefromwaitlist`	Rimuove la prima voce attiva della lista d'attesa oppure la voce attiva numerata in `value`	`https://io.socialstream.ninja/SESSIONID/removefromwaitlist/null/1`
`highlightwaitlist`	Mette in evidenza la prima voce attiva della lista d'attesa, oppure la voce attiva numerata in `value`	`https://io.socialstream.ninja/SESSIONID/highlightwaitlist/null/1`
`stopentries` / `startentries`	Sospende o riprende le nuove iscrizioni alla lista d'attesa senza cancellare quelle esistenti. `openentries` e `resumeentries` sono alias di `startentries`.	`https://io.socialstream.ninja/SESSIONID/stopentries`
`selectwinner`	Seleziona uno o più vincitori casuali dalla lista d'attesa o dall'estrazione	`https://io.socialstream.ninja/SESSIONID/selectwinner/null/1`
`downloadwaitlist`	Scarica la lista d'attesa attuale come file TSV dalla pagina o app Social Stream in esecuzione	`https://io.socialstream.ninja/SESSIONID/downloadwaitlist`
`drawmode`	Attiva o disattiva la modalità estrazione, oppure ne cambia lo stato quando `value` è uguale a `toggle`	`https://io.socialstream.ninja/SESSIONID/drawmode/null/toggle`
`waitlistmessage`	Imposta il messaggio del titolo della lista d'attesa o dell'estrazione mostrato nella pagina della lista	`https://io.socialstream.ninja/SESSIONID/waitlistmessage/null/Type%20!join%20to%20enter`
`resetwaitlist`	Svuota la lista d'attesa e riapre le iscrizioni	`https://io.socialstream.ninja/SESSIONID/resetwaitlist`

Visualizza la documentazione API completa

Ambiente di prova API interattivo

Prova l'API con il nostro ambiente interattivo che offre facile accesso a tutti i comandi e le funzioni:

Per un insieme più piccolo di pulsanti di controllo della diretta in OBS, usa il Dock di controllo Social Stream e segui Guida alla configurazione di OBS.

Apri l'ambiente di prova API

Prova i comandi

Prova tutti i comandi API in un ambiente sicuro

Genera codice

Ottieni esempi di codice per HTTP, WebSocket e SSE

Visualizza i risultati

Visualizza in tempo reale le risposte ai tuoi comandi

Crea prove

Genera messaggi di prova con contenuto casuale

Nota: Ricorda di sostituire SESSIONID con il tuo vero ID di sessione di Social Stream Ninja!

StreamDeck e Companion

Integrazione StreamDeck

Social Stream Ninja si integra con StreamDeck in vari modi: azioni HTTP native e integrazione Bitfocus Companion.

Metodo HTTP/API

Usa l'azione «Website» di StreamDeck con «GET request in background» attivo per inviare comandi direttamente all'API.

Bitfocus Companion

Integrazione nativa con azioni pronte, riscontri in tempo reale e variabili per contenuti dinamici.

Integrazione con Companion

Bitfocus Companion offre un ampio controllo di Social Stream Ninja tramite API WebSocket o HTTP.

Azione	Descrizione	Metodo API
Rimuovi il messaggio in evidenza	Rimuove dall'overlay il messaggio attualmente in evidenza	WebSocket/HTTP
Successivo in coda	Mostra il messaggio successivo in coda	WebSocket/HTTP
Attiva/disattiva visualizzazione automatica	Attiva o disattiva la messa in evidenza automatica dei messaggi	WebSocket/HTTP
Invia messaggio in chat	Invia un messaggio a tutte le piattaforme connesse	WebSocket/HTTP

Variabili dinamiche

featured_message - Testo del messaggio attualmente in evidenza
featured_username - Nome utente attualmente in evidenza
queue_size - Numero di messaggi in coda

Risorse per la configurazione

Ottieni Companion Documentazione del modulo

Integrazione IA

Modalità bot di chat IA

Social Stream Ninja offre un'integrazione IA completa per arricchire le dirette con risposte alla chat, moderazione e altro. Scegli provider IA locali o nel cloud in base alle tue esigenze.

Risposte automatiche alla chat

Lascia che l'IA interagisca automaticamente con gli spettatori, rispondendo alle domande e mantenendo viva la conversazione anche quando sei concentrato sui contenuti.

Moderazione dei contenuti

Usa l'IA per aiutarti a moderare la chat, individuando messaggi potenzialmente dannosi e gestendoli automaticamente secondo le tue preferenze. Scegli tra modalità non bloccante e blocco rigoroso.

Ricerca RAG

Retrieval-Augmented Generation permette all'IA di cercare nella tua base di conoscenza personalizzata per fornire risposte accurate e specifiche per i tuoi contenuti.

Più istanze di bot

Esegui diverse istanze di bot per vari scopi: bot di chat pubblico, bot privato individuale, bot di censura e persino un co-conduttore IA multimodale capace di vedere e ascoltare.

Provider IA supportati

Social Stream Ninja supporta diversi provider IA, da modelli interamente locali nel browser o nel runtime fino alle API ospitate:

Ollama (API locale nativa)

Modelli IA gratuiti, orientati alla privacy e ospitati sul tuo computer tramite l'API nativa di Ollama.

Local Gemma 4

Esegui Gemma 4 nel browser dopo aver copiato i file del modello sul tuo host delle risorse; l'host largefiles di SSN attualmente non include le risorse Gemma.

Local Qwen 3.5

Esegui Qwen 3.5 nel browser usando i file del modello ospitati da te, per risposte locali e private.

ChatGPT / OpenAI

API OpenAI, inclusi i moderni modelli di chat e voce in tempo reale.

Google Gemini

Modelli Google Gemini, incluse le attuali opzioni testuali e multimodali dal vivo di Gemini 2.5.

DeepSeek

Modelli IA efficienti ed economici, ottimizzati per le conversazioni.

xAI (Grok)

API xAI Grok, incluse le sessioni vocali in tempo reale con segreti client temporanei.

AWS Bedrock

Modelli IA di livello aziendale di vari provider, tra cui Claude e Llama.

OpenRouter

Accesso a più modelli IA tramite un'interfaccia API unificata.

Groq

Inferenza per chat compatibile con OpenAI a bassa latenza, per risposte rapide nelle conversazioni.

API personalizzata (compatibile con OpenAI)

Collegati a llama.cpp, LM Studio, vLLM o a qualsiasi altro endpoint compatibile con OpenAI.

Nota: Ollama usa la sua API nativa. Per llama.cpp, LM Studio, vLLM o altri server compatibili con OpenAI, scegli API personalizzata.

Integrazione della sintesi vocale

Social Stream Ninja offre un supporto TTS completo per i messaggi dei bot e i contenuti della chat in evidenza:

TTS di sistema

TTS gratuito e integrato che usa il sintetizzatore vocale del sistema operativo.

Kokoro

TTS gratuito eseguito localmente con WebGPU/CPU per chi tiene alla privacy.

Kitten TTS

TTS leggero basato sul browser, che scarica un piccolo modello per generare la voce localmente.

ElevenLabs

Sintesi vocale premium con voci naturali e personalizzabili.

Google Cloud TTS

Voci di alta qualità con numerose lingue e opzioni di personalizzazione.

Gemini (TTS in anteprima)

Modelli vocali neurali di Google in anteprima, con scelta di voce e lingua.

Speechify

Sintesi vocale basata sull'IA con funzionalità naturali di conversione della voce.

OpenAI TTS

Sintesi vocale OpenAI con scelta di voci, modelli ed endpoint compatibili facoltativi.

Nota: Il TTS richiede che la pagina overlay appropriata sia aperta in OBS. Ogni provider TTS offre diverse voci, latenze, tariffe o requisiti hardware.

Istanze dei bot e overlay

Social Stream Ninja offre più istanze di bot per diversi casi d'uso:

Tipo di bot	URL	Descrizione
Bot di chat principale	`/bot.html`	Overlay del bot principale con TTS facoltativo e risposte nella chat pubblica
Interfaccia di chat privata	`/chatbot.html`	Pagina bot dedicata alle conversazioni individuali, che non condivide il dataset RAG o la cronologia della chat del bot principale
Bot di censura	(in esecuzione in background)	Filtra, ripulisce o blocca automaticamente i messaggi in arrivo
Co-conduttore IA	`/cohost.html`	IA multimodale che può vedere lo schermo, ascoltare audio e interagire

Configurazione dell'integrazione IA

Segui questi passaggi per configurare l'integrazione IA con il menu attuale:

1

Scegli e collega il tuo provider LLM

Seleziona il provider in Configura provider del servizio LLM (Configure LLM Service Provider) e compila i campi corrispondenti:

Ollama: Installa localmente e imposta l'endpoint se necessario
Local Gemma / Local Qwen: Usa file di modelli per browser ospitati e, facoltativamente, una cartella del modello alternativa; Qwen può usare largefiles di SSN, mentre Gemma richiede una tua cartella mirror
ChatGPT, Gemini, DeepSeek, xAI, Groq, OpenRouter, Bedrock: Aggiungi la tua chiave API e il modello preferito
API personalizzata (Custom API): Inserisci un endpoint compatibile con OpenAI, l'ID del modello e, facoltativamente, una chiave API

2

Prova il bot di chat selezionato

Usa il pulsante integrato Prova il bot di chat selezionato per verificare provider, modello e credenziali prima della diretta.

3

Configura il comportamento del bot

Personalizza il comportamento del bot nella chat:

Attiva il bot di chat LLM IA (Enable the LLM AI chat bot)
Imposta nome del bot, parole di attivazione e limite di frequenza delle risposte
Scegli se inviare le risposte alla chat o solo alla pagina overlay del bot
Aggiungi istruzioni personalizzate per tono, ruolo e regole di moderazione

4

Attiva le funzioni aggiuntive facoltative

Attiva le funzioni che desideri intorno al bot:

Attiva TTS per le risposte del bot e scegli un provider
Scegli la scomparsa automatica a tempo fisso, in base alla lunghezza del messaggio o dopo il TTS per /bot.html; usa clearBotOverlay per la cancellazione manuale
Attiva RAG e carica documenti per ottenere risposte basate sulle tue conoscenze
Attiva il bot di censura per la moderazione o la modalità di blocco rigoroso
Apri /bot.html, /chatbot.html, oppure /cohost.html in OBS o in un browser, secondo necessità

Documentazione dettagliata

Per istruzioni complete e informazioni più approfondite sul TTS, consulta queste guide:

Guida alla configurazione del bot di chat IA Guida al TTS con IA locale Account bot per le risposte automatiche Download ufficiale di Ollama

Controllo MIDI e scorciatoie

Integrazione MIDI

Controlla Social Stream Ninja tramite controller MIDI, scorciatoie da tastiera o StreamDeck con plugin MIDI.

Requisiti di configurazione

Attiva il supporto MIDI nelle impostazioni dell'estensione
Installa un dispositivo MIDI virtuale di loopback, per esempio loopMIDI
Configura il controller MIDI o il plugin MIDI di StreamDeck

Numero CC	Valore	Azione	Note
102	1	Invia «1» in chat	Reazione rapida
102	2	Invia «LUL» in chat	Reazione con emote
102	3	Racconta una barzelletta	Attiva la risposta del bot
102	4	Cancella overlay	Rimuove il messaggio in evidenza

Suggerimento: Il controllo MIDI funziona meglio con controller fisici, ma può essere attivato anche tramite dispositivi MIDI virtuali.

Supporto delle scorciatoie

Usa scorciatoie da tastiera per accedere rapidamente alle funzioni comuni.

Le scorciatoie possono essere configurate nelle impostazioni del menu e funzionano a livello di sistema quando il browser è in primo piano o quando si usa l'app.

Integrazione webhook

Servizi di donazione

Social Stream Ninja può ricevere donazioni ed eventi da servizi esterni tramite webhook; di seguito alcuni dei più popolari:

Stripe

Elabora le donazioni con carta di credito direttamente tramite il tuo account Stripe.

Crea un link di pagamento su stripe.com
Nella dashboard Stripe, vai a Sviluppatori → Webhook
Aggiungi endpoint: https://io.socialstream.ninja/SESSIONID/stripe
Seleziona l'evento checkout.session.completed
Aggiungi &server all'URL del dock

Ko-Fi

Ricevi donazioni per un caffè dai tuoi sostenitori.

Accedi al tuo account Ko-Fi
Vai a Impostazioni webhook
Aggiungi https://io.socialstream.ninja/SESSIONID/kofi come URL del webhook
Aggiungi &server all'URL del dock
Prova con il pulsante «Send Single Donation Test»

Buy Me A Coffee

Raccogli donazioni tramite la popolare piattaforma Buy Me A Coffee.

Accedi al tuo account Buy Me A Coffee
Apri le impostazioni dei webhook
Aggiungi https://io.socialstream.ninja/SESSIONID/bmac come URL del webhook
Aggiungi &server all'URL del dock per ricevere eventi
Sono supportati sia gli eventi di donazione sia quelli di abbonamento

Nota sulla sicurezza: Mantieni privato l'ID della sessione: chiunque lo conosca può inviare donazioni simulate al tuo overlay. L'URL del webhook deve essere trattato come informazione sensibile.

Integrazione di servizi esterni

Social Stream Ninja può anche inviare dati a servizi esterni:

Servizio	Parametro URL	Descrizione
Singular Live	`&singular=IDENTIFIER`	Invia i messaggi selezionati a Singular Live per l'overlay dei messaggi in evidenza
H2R	`&h2r=IDENTIFIER`	Invia i messaggi selezionati a un server H2R locale
POST generico	`&postserver=URL`	Invia i messaggi selezionati a un endpoint personalizzato tramite POST
PUT generico	`&putserver=URL`	Invia i messaggi selezionati a un endpoint personalizzato tramite PUT

Questi parametri vanno aggiunti all'URL della pagina del dock.

Script personalizzati

JavaScript personalizzato

Puoi creare i tuoi comandi e le tue funzioni personalizzando il codice JavaScript:

Usare custom.js

Rinomina custom_sample.js con il nome di file custom.js
Modifica il file per aggiungere le tue funzionalità
Apri il file dock.html localmente per caricare custom.js

Questo metodo consente personalizzazioni e attivazioni complesse.

Overlay personalizzati

Creare overlay personalizzati

Puoi creare overlay di chat completamente personalizzati da zero, adatti allo stile e alle funzioni della tua diretta. Social Stream Ninja offre una base flessibile su cui costruire.

Partire da un modello

Inizia dal nostro modello di overlay di esempio per comprenderne le basi:

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

Questo modello minimale include solo il codice essenziale per un overlay funzionante.

Visualizza l'overlay di esempio

Funzioni principali da personalizzare

Alterna i messaggi in evidenza e la visualizzazione di tutti i messaggi
Personalizza l'aspetto con CSS
Aggiungi animazioni personalizzate per i nuovi messaggi
Implementa il tuo filtro dei messaggi
Aggiungi elementi interattivi con JavaScript

Passaggi di implementazione

Scarica il file HTML dell'overlay di esempio
Modifica l'HTML per la tua disposizione personalizzata
Personalizza il CSS per ottenere l'aspetto desiderato
Modifica il JavaScript secondo necessità per ottenere comportamenti personalizzati
Salva il file localmente per usarlo in OBS come sorgente browser

API del timer

Controllo remoto di `timer.html`

La pagina del timer ha intenzionalmente funzioni limitate: un solo timer, controlli facoltativi per l'operatore, stati di avviso, tempo supplementare e alcuni stili visivi.

Tra le azioni utili ci sono starttimer, pausetimer, resettimer, timeradd, timersubtract, e settimer.

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

Per conoscere lo stato attuale del timer, usa gettimerstate con un token di callback.

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

Usa la pagina con timer.html?session=YOUR_SESSION&server se vuoi controllarlo direttamente tramite il server API.