Comandos y API - Social Stream Ninja

Comandos del bot

Comandos de bot integrados

Social Stream Ninja incluye varios comandos integrados que tus espectadores pueden usar en el chat o que puedes activar mediante la API.

Comando	Descripción	Cómo activarlo
`!joke`	Responde con un chiste friki de padre al azar	Actívalo mediante el interruptor del menú de la extensión
`hi`	Da la bienvenida automáticamente a quien diga «hi» en el chat	Actívalo mediante el interruptor del menú de la extensión
`!cycle`	Cuando está activado, permite que los espectadores cambien escenas de OBS	Actívalo mediante el interruptor del menú de la extensión

Nota: Los comandos del bot solo funcionan si las respuestas automáticas están configuradas correctamente y tienes permiso para publicar mensajes en las plataformas correspondientes.

Configuración de respuestas automáticas

Para que las respuestas automáticas funcionen correctamente:

Asegúrate de haber iniciado sesión en la plataforma (YouTube, Twitch, etc.)
Comprueba que la ventana de chat esté visible, no minimizada
Prueba primero a enviar un mensaje manualmente para confirmar los permisos
Activa los interruptores de los comandos correspondientes en el menú de la extensión

Si ves una barra azul de depuración cuando se activan las respuestas automáticas, puedes ocultarla iniciando Chrome con el parámetro --silent-debugger-extension-api .

API del servidor

Descripción general

Social Stream Ninja ofrece una API potente para controlar por programación todos los aspectos de tu configuración de streaming. El servidor de API puede enviar comandos a tu configuración y escuchar mensajes entrantes de los servicios de chat combinados.

Gestión de overlays

Controla mensajes destacados, vacía overlays y modifica el aspecto del contenido en tu directo.

Integración de webhooks

Recibe eventos de servicios externos como Stripe, Ko-Fi y Buy Me A Coffee.

Exportación de mensajes

Exporta mensajes de chat a un archivo o reenvíalos mediante un webhook POST para integraciones personalizadas.

Ajustes necesarios (Ajustes globales → Mecánica):

🎮 Control remoto (StreamDeck/Bitfocus): Activa «Activar el control remoto de la extensión por API» (Enable remote API control of extension) (Interruptor 1) — Conecta a canal 1
📡 Receptor de chat (aplicaciones Python/Node): Activa el interruptor 1 + «Enviar mensajes de chat al servidor de la API» (Send chat messages to API server) (Interruptor 3) — Conecta a canal 4

Consulta: documentación completa de la API para guías detalladas de configuración y ejemplos de código.

Endpoints de API y métodos de conexión

HTTP GET/POST

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

Ideal para comandos sencillos desde Stream Deck o scripts personalizados.

WebSocket

wss://io.socialstream.ninja:443

Para comunicación bidireccional en tiempo real con reconexión automática.

Si prefieres mantener conexiones entre pares sin activar el modo WebSocket, puedes usar el SDK WebRTC de Social Stream Ninja. Incluye ejemplos de Node y navegador como el receptor de Social Stream Ninja.

Server-Sent Events

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

Para actualizaciones unidireccionales en tiempo real desde el servidor.

Sistema de canales

La API usa un sistema de canales para enrutar mensajes:

	- 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

Conecta con el canal que quieras:

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

Comandos comunes de API

Acción	Descripción	Ejemplo
`sendChat`	Envía un mensaje a todas las plataformas de chat conectadas	`https://io.socialstream.ninja/SESSIONID/sendChat/null/Hello everyone!`
`sendEncodedChat`	Envía un mensaje codificado para URL a todas las plataformas	`https://io.socialstream.ninja/SESSIONID/sendEncodedChat/null/Hello%20everyone%21`
`clearOverlay`	Quita el mensaje destacado del overlay	`https://io.socialstream.ninja/SESSIONID/clearOverlay`
`nextInQueue`	Muestra el siguiente mensaje de la cola	`https://io.socialstream.ninja/SESSIONID/nextInQueue`
`autoShow`	Alterna el destacado automático de mensajes	`https://io.socialstream.ninja/SESSIONID/autoShow/toggle`
`blockUser`	Bloquea a un usuario de una plataforma concreta	`https://io.socialstream.ninja/SESSIONID/blockUser/null/{"chatname":"username","type":"twitch"}`
`extContent`	Envía contenido externo como mensaje de chat	`https://io.socialstream.ninja/SESSIONID/extContent/null/{"chatname":"User","chatmessage":"Hello"}`
`pin`	Fija un mensaje existente del dock mediante su ID o fija un objeto de mensaje completo. Requiere `dock.html` abierto en la misma sesión.	`https://io.socialstream.ninja/SESSIONID/pin/null/MESSAGE_MID`
`unpin`	Desfija un mensaje existente del dock mediante su ID. Usa el campo o segmento de ruta target para un dock con etiqueta.	`https://io.socialstream.ninja/SESSIONID/unpin/null/MESSAGE_MID`
`nextPinned`	Destaca el primer mensaje fijado en el dock.	`https://io.socialstream.ninja/SESSIONID/nextPinned`
`removefromwaitlist`	Elimina la primera entrada activa de la lista de espera o la entrada activa numerada en `value`	`https://io.socialstream.ninja/SESSIONID/removefromwaitlist/null/1`
`highlightwaitlist`	Destaca la primera entrada activa de la lista de espera o la entrada activa numerada en `value`	`https://io.socialstream.ninja/SESSIONID/highlightwaitlist/null/1`
`stopentries` / `startentries`	Detiene o reanuda las nuevas inscripciones en la lista de espera sin vaciar la lista existente. `openentries` y `resumeentries` son alias de `startentries`.	`https://io.socialstream.ninja/SESSIONID/stopentries`
`selectwinner`	Selecciona uno o varios ganadores aleatorios de la lista de espera o sorteo	`https://io.socialstream.ninja/SESSIONID/selectwinner/null/1`
`downloadwaitlist`	Descarga la lista de espera actual como archivo TSV desde la página o aplicación de Social Stream en ejecución	`https://io.socialstream.ninja/SESSIONID/downloadwaitlist`
`drawmode`	Activa o desactiva el modo sorteo, o lo alterna cuando `value` es igual a `toggle`	`https://io.socialstream.ninja/SESSIONID/drawmode/null/toggle`
`waitlistmessage`	Establece el título de la lista de espera o sorteo que se muestra en su página	`https://io.socialstream.ninja/SESSIONID/waitlistmessage/null/Type%20!join%20to%20enter`
`resetwaitlist`	Vacía la lista de espera y vuelve a abrir las inscripciones	`https://io.socialstream.ninja/SESSIONID/resetwaitlist`

Ver la documentación completa de la API

Entorno interactivo de pruebas de API

Prueba la API con nuestro entorno interactivo, que facilita el acceso a todos los comandos y funciones:

Para un conjunto más pequeño de botones del directo en OBS, usa el Dock de control de Social Stream y sigue la guía de configuración de OBS.

Abrir entorno de pruebas de API

Probar comandos

Prueba todos los comandos de API en un entorno seguro

Generar código

Obtén ejemplos de código para HTTP, WebSocket y SSE

Ver resultados

Ve las respuestas a tus comandos en tiempo real

Crear pruebas

Genera mensajes de prueba con contenido aleatorio

Nota: Recuerda sustituir SESSIONID por tu ID de sesión real de Social Stream Ninja.

StreamDeck y Companion

Integración con StreamDeck

Social Stream Ninja se integra con StreamDeck mediante varios métodos: acciones HTTP nativas e integración con Bitfocus Companion.

Método HTTP/API

Usa la acción «Website» de StreamDeck con «GET request in background» activado para enviar comandos directamente a la API.

Bitfocus Companion

Integración nativa con acciones predefinidas, información en tiempo real y variables para contenido dinámico.

Integración con Companion

Bitfocus Companion ofrece un control avanzado de Social Stream Ninja mediante API WebSocket o HTTP.

Acción	Descripción	Método de API
Borrar mensaje destacado	Quita del overlay el mensaje destacado actual	WebSocket/HTTP
Siguiente en cola	Muestra el siguiente mensaje en cola	WebSocket/HTTP
Alternar visualización automática	Activa o desactiva el destacado automático de mensajes	WebSocket/HTTP
Enviar mensaje de chat	Envía un mensaje a todas las plataformas conectadas	WebSocket/HTTP

Variables dinámicas

featured_message - Texto del mensaje destacado actual
featured_username - Nombre de usuario destacado actual
queue_size - Número de mensajes en la cola

Recursos de configuración

Obtener Companion Documentación del módulo

Integración de IA

Modo de chatbot con IA

Social Stream Ninja ofrece una amplia integración de IA para mejorar tus directos con respuestas de chat, moderación y mucho más. Elige proveedores locales o en la nube según tus necesidades.

Respuestas automáticas al chat

Deja que la IA interactúe automáticamente con tus espectadores, responda preguntas y anime la conversación incluso mientras te concentras en tu contenido.

Moderación de contenido

Usa IA para ayudar a moderar el chat identificando mensajes potencialmente dañinos y gestionándolos automáticamente según tus preferencias. Elige entre modo sin bloqueo o de bloqueo estricto.

Búsqueda RAG

La generación aumentada por recuperación permite que la IA busque en tu base de conocimiento personalizada para dar respuestas precisas relacionadas con tu contenido.

Varias instancias de bot

Ejecuta distintas instancias de bot para diversos fines: chatbot público, bot privado individual, bot de censura e incluso un copresentador multimodal con IA que ve y oye.

Proveedores de IA compatibles

Social Stream Ninja admite varios proveedores de IA, desde modelos completamente locales en navegador o entorno de ejecución hasta API alojadas:

Ollama (API local nativa)

Modelos de IA gratuitos, privados y autoalojados que se ejecutan en tu equipo mediante la API propia de Ollama.

Local Gemma 4

Ejecuta Gemma 4 en el navegador tras copiar los archivos del modelo a tu propio servidor de recursos; el servidor largefiles de SSN actualmente no incluye recursos de Gemma.

Local Qwen 3.5

Ejecuta Qwen 3.5 en el navegador desde tus propios archivos de modelo alojados para respuestas locales y privadas.

ChatGPT / OpenAI

API de OpenAI, incluidos modelos modernos de chat y voz en tiempo real.

Google Gemini

Modelos de Google Gemini, incluidas las opciones actuales de texto y multimodales en directo de Gemini 2.5.

DeepSeek

Modelos de IA eficientes y económicos optimizados para tareas de conversación.

xAI (Grok)

API de xAI Grok, incluidas sesiones de voz en tiempo real al usar secretos de cliente temporales.

AWS Bedrock

Modelos de IA de nivel empresarial de varios proveedores, incluidos Claude y Llama.

OpenRouter

Acceso a varios modelos de IA mediante una interfaz de API unificada.

Groq

Inferencia de chat de baja latencia compatible con OpenAI para respuestas de conversación rápidas.

API personalizada compatible con OpenAI

Conecta con llama.cpp, LM Studio, vLLM o cualquier otro endpoint compatible con OpenAI.

Nota: Ollama usa su propia API nativa. Para llama.cpp, LM Studio, vLLM u otros servidores compatibles con OpenAI, elige API personalizada.

Integración de texto a voz

Social Stream Ninja incluye amplia compatibilidad de TTS para mensajes del bot y contenido de chat destacado:

TTS del sistema

TTS gratuito integrado que usa el sintetizador de voz de tu sistema operativo.

Kokoro

TTS gratuito que se ejecuta localmente con WebGPU/CPU para usuarios que priorizan la privacidad.

Kitten TTS

TTS ligero en el navegador que descarga un modelo pequeño para generar voz localmente.

ElevenLabs

Síntesis de voz prémium con voces naturales y personalizables.

Google Cloud TTS

Voces de alta calidad con amplias opciones de idiomas y personalización.

Gemini (TTS en vista previa)

Modelos de voz neuronal en vista previa de Google con opciones de voz e idioma seleccionables.

Speechify

Texto a voz con IA y capacidades de conversión de voz natural.

OpenAI TTS

Síntesis de voz de OpenAI con voces y modelos seleccionables y endpoints compatibles opcionales.

Nota: La función TTS requiere que la página de overlay adecuada esté abierta en OBS. Cada proveedor ofrece distintas voces, latencia, precios o requisitos de hardware.

Instancias de bots y overlays

Social Stream Ninja ofrece varias instancias de bot para distintos usos:

Tipo de bot	URL	Descripción
Chatbot principal	`/bot.html`	Overlay del bot principal con TTS opcional y respuestas al chat público
Interfaz de chat privado	`/chatbot.html`	Página de bot individual que no comparte el conjunto de datos RAG ni el historial de chat del bot principal
Bot de censura	(se ejecuta en segundo plano)	Filtra, sanea o bloquea mensajes entrantes automáticamente
Copresentador con IA	`/cohost.html`	IA multimodal que puede ver tu pantalla, oír audio e interactuar

Configurar la integración de IA

Sigue estos pasos para configurar la integración de IA con el menú actual:

1

Elige y conecta tu proveedor LLM

Selecciona tu proveedor en Configurar proveedor de servicio LLM (Configure LLM Service Provider) y rellena los campos correspondientes:

Ollama: Instálalo localmente y establece el endpoint si hace falta
Local Gemma / Local Qwen: Usa recursos de modelos alojados para navegador y una carpeta de modelo alternativa opcional; Qwen puede usar largefiles de SSN, mientras que Gemma necesita tu propia carpeta espejo
ChatGPT, Gemini, DeepSeek, xAI, Groq, OpenRouter, Bedrock: Añade tu clave de API y el modelo preferido
API personalizada: Introduce un endpoint compatible con OpenAI, el ID del modelo y una clave de API opcional

2

Prueba el chatbot seleccionado

Usa la opción integrada Probar chatbot seleccionado (Test selected chat bot) para comprobar proveedor, modelo y credenciales antes de emitir.

3

Configura el comportamiento del bot

Personaliza el comportamiento del bot en el chat:

Activar el bot de chat de IA LLM (Enable the LLM AI chat bot)
Establece el nombre del bot, las palabras activadoras y el límite de frecuencia de respuesta
Elige si las respuestas vuelven al chat o solo a la página de overlay del bot
Añade instrucciones personalizadas de tono, rol y reglas de moderación

4

Activa extras opcionales

Activa las funciones que quieras para el bot:

Activa TTS para las respuestas del bot y elige un proveedor
Elige ocultación automática con tiempo fijo, según la longitud del mensaje o después del TTS para /bot.html; usa clearBotOverlay para borrado manual
Activa RAG y sube documentos para obtener respuestas basadas en tu información
Activa el bot de censura para moderación o el modo de bloqueo estricto
Abrir /bot.html, /chatbot.html, o /cohost.html en OBS o en un navegador según necesites

Documentación detallada

Para instrucciones completas de configuración y más detalles de TTS, usa estas guías:

Guía de configuración del chatbot con IA Guía de TTS local con IA Cuentas de bot para respuestas automáticas Descarga oficial de Ollama

Control con MIDI y atajos

Integración MIDI

Controla Social Stream Ninja con controladores MIDI, atajos de teclado o StreamDeck con plugins MIDI.

Requisitos de configuración

Activa la compatibilidad MIDI en los ajustes de la extensión
Instala un dispositivo MIDI virtual de bucle de retorno (p. ej., loopMIDI)
Configura tu controlador MIDI o el plugin MIDI de StreamDeck

Número CC	Valor	Acción	Notas
102	1	Enviar «1» al chat	Reacción rápida
102	2	Enviar «LUL» al chat	Reacción con emote
102	3	Contar un chiste	Activa una respuesta del bot
102	4	Vaciar overlay	Quita el mensaje destacado

Consejo: El control MIDI funciona mejor con controladores físicos, pero también puede activarse mediante dispositivos MIDI virtuales.

Compatibilidad con atajos de teclado

Usa atajos de teclado para acceder rápidamente a funciones comunes.

Los atajos se pueden configurar en los ajustes del menú y funcionan en todo el sistema cuando el navegador tiene el foco o cuando se usa la aplicación.

Integración de webhooks

Servicios de donaciones

Social Stream Ninja puede recibir donaciones y eventos de servicios externos mediante webhooks; estos son algunos de los más populares:

Stripe

Procesa donaciones con tarjeta directamente mediante tu cuenta de Stripe.

Crea un enlace de pago en stripe.com
En el panel de Stripe, ve a Desarrolladores → Webhooks
Añade el endpoint: https://io.socialstream.ninja/SESSIONID/stripe
Selecciona el evento checkout.session.completed
Añade &server a la URL de tu dock

Ko-Fi

Recibe donaciones de café de quienes te apoyan.

Inicia sesión en tu cuenta de Ko-Fi
Ve a Ajustes de webhooks
Añade https://io.socialstream.ninja/SESSIONID/kofi como URL del webhook
Añade &server a la URL de tu dock
Prueba con el botón «Send Single Donation Test»

Buy Me A Coffee

Recoge donaciones mediante la popular plataforma Buy Me A Coffee.

Inicia sesión en tu cuenta de Buy Me A Coffee
Ve a los ajustes de webhooks
Añade https://io.socialstream.ninja/SESSIONID/bmac como URL del webhook
Añade &server a la URL de tu dock para recibir eventos
Se admiten eventos tanto de donaciones como de membresías

Nota de seguridad: Mantén privado tu ID de sesión, ya que cualquiera que lo tenga puede enviar donaciones falsas a tu overlay. Trata la URL del webhook como información confidencial.

Integración de servicios externos

Social Stream Ninja también puede enviar datos a servicios externos:

Servicio	Parámetro de URL	Descripción
Singular Live	`&singular=IDENTIFIER`	Envía mensajes seleccionados a Singular Live para un overlay de mensajes destacados
H2R	`&h2r=IDENTIFIER`	Envía mensajes seleccionados a un servidor local de H2R
POST genérico	`&postserver=URL`	Envía mensajes seleccionados a un endpoint personalizado mediante POST
PUT genérico	`&putserver=URL`	Envía mensajes seleccionados a un endpoint personalizado mediante PUT

Estos parámetros deben añadirse a la URL de la página del dock.

Scripts personalizados

JavaScript personalizado

Puedes crear tus propios comandos y funciones personalizando el código JavaScript:

Usar custom.js

Renombrar custom_sample.js con el nombre de archivo custom.js
Edita el archivo para añadir tus funciones personalizadas
Abre el archivo dock.html localmente para que se cargue custom.js

Este método permite personalizaciones y disparadores complejos.

Overlays personalizados

Crear overlays personalizados

Puedes crear overlays de chat completamente personalizados desde cero para adaptarlos al estilo y las funciones de tu directo. Social Stream Ninja ofrece una base flexible sobre la que construir.

Empezar con una plantilla

Empieza con nuestra plantilla de overlay de ejemplo para comprender lo básico:

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

Esta plantilla mínima incluye solo el código esencial para un overlay funcional.

Ver overlay de ejemplo

Funciones principales para personalizar

Alternar entre mensajes destacados y todos los mensajes
Personaliza el aspecto con CSS
Añade animaciones personalizadas para mensajes nuevos
Implementa tu propio filtrado de mensajes
Añade elementos interactivos con JavaScript

Pasos de implementación

Descarga el archivo HTML del overlay de ejemplo
Edita el HTML para crear tu diseño personalizado
Personaliza el CSS para obtener el aspecto deseado
Modifica el JavaScript según necesites para comportamientos personalizados
Guarda el archivo localmente para usarlo en OBS como fuente de navegador

API del temporizador

Control remoto de `timer.html`

La página del temporizador tiene un alcance limitado intencionadamente: un temporizador, controles opcionales del operador, estados de aviso, tiempo extra y algunos estilos visuales.

Entre las acciones útiles están starttimer, pausetimer, resettimer, timeradd, timersubtract, y settimer.

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

Para consultar el estado actual del temporizador, usa gettimerstate con un token de callback.

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

Usa la página con timer.html?session=YOUR_SESSION&server si quieres controlarla directamente mediante el servidor de API.