Commands & API

Control Social Stream Ninja with built-in commands, automation, and API integration

Bot Commands

Built-in Bot Commands

Social Stream Ninja includes several built-in commands that your viewers can use in chat, or that you can trigger via the API.

Command Description How to Enable
!joke Tells a random geeky dad joke in response Enable via the extension menu toggle
hi Automatically welcomes anyone who says "hi" in chat Enable via the extension menu toggle
!cycle When enabled, allows viewers to change OBS scenes Enable via the extension menu toggle

Note: Bot commands will only work when the auto-responder is properly configured and you have permission to post messages in the respective platforms.

Auto-Response Configuration

For the auto-responder to work properly:

  1. Ensure you're logged into the platform (YouTube, Twitch, etc.)
  2. Make sure the chat window is visible (not minimized)
  3. Try manually sending a test message first to confirm permissions
  4. Enable the specific command toggles in the extension menu

If you see a blue debugging bar when auto-responses are triggered, you can hide it by starting Chrome with the --silent-debugger-extension-api flag.

Server API

Overview

Social Stream Ninja provides a powerful API that allows you to control every aspect of your streaming setup programmatically. The API server can both issue commands to your setup and listen to incoming messages from consolidated chat services.

Overlay Management

Control featured messages, clear overlays, and manipulate content appearance in your stream.

Webhook Integration

Receive events from third-party services like Stripe, Ko-Fi, and Buy Me A Coffee.

Message Export

Export chat messages to file or forward them via webhook (POST) for custom integrations.

Required Settings (Global settings → Mechanics):

  • 🎮 Remote Control (StreamDeck/Bitfocus): Enable "Enable remote API control of extension" (Toggle 1) — Connect to channel 1
  • 📡 Chat Listener (Python/Node apps): Enable Toggle 1 + "Send chat messages to API server" (Toggle 3) — Connect to channel 4

See the full API documentation for detailed setup guides and code samples.

API Endpoints and Connection Methods

HTTP GET/POST

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

Perfect for simple commands from Stream Deck or custom scripts.

WebSocket

wss://io.socialstream.ninja:443

For real-time bidirectional communication with auto-reconnection.

If you prefer to keep connections peer-to-peer without enabling WebSocket mode, you can use the Social Stream Ninja WebRTC SDK. It includes Node and browser samples such as the Social Stream Ninja listener.

Server-Sent Events

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

For one-way real-time updates from the server.

Channel System

The API uses a channel system for message routing:

	- 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

Connect with your desired channel:

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

Common API Commands

Action Description Example
sendChat Sends a message to all connected chat platforms https://io.socialstream.ninja/SESSIONID/sendChat/null/Hello everyone!
sendEncodedChat Sends a URL-encoded message to all platforms https://io.socialstream.ninja/SESSIONID/sendEncodedChat/null/Hello%20everyone%21
clearOverlay Clears the featured message from the overlay https://io.socialstream.ninja/SESSIONID/clearOverlay
nextInQueue Displays the next message in the queue https://io.socialstream.ninja/SESSIONID/nextInQueue
autoShow Toggles automatic featuring of messages https://io.socialstream.ninja/SESSIONID/autoShow/toggle
blockUser Blocks a user from a specific platform https://io.socialstream.ninja/SESSIONID/blockUser/null/{"chatname":"username","type":"twitch"}
extContent Sends external content as a chat message https://io.socialstream.ninja/SESSIONID/extContent/null/{"chatname":"User","chatmessage":"Hello"}
View Complete API Documentation

Interactive API Sandbox

Try out the API with our interactive sandbox that provides easy access to all commands and features:

Open API Sandbox

Test Commands

Try all API commands in a safe environment

Generate Code

Get code examples for HTTP, WebSocket, and SSE

View Results

See real-time responses from your commands

Create Tests

Generate test messages with random content

Note: Remember to replace SESSIONID with your actual session ID from Social Stream Ninja!

StreamDeck & Companion

StreamDeck Integration

Social Stream Ninja integrates with StreamDeck through multiple methods: native HTTP actions and Bitfocus Companion integration.

HTTP/API Method

Use StreamDeck's "Website" action with "GET request in background" enabled to send commands directly to the API.

Bitfocus Companion

Native integration with pre-built actions, real-time feedback, and variables for dynamic content.

Companion Integration

Bitfocus Companion provides powerful control of Social Stream Ninja using either WebSocket or HTTP APIs.

Action Description API Method
Clear Featured Message Removes the currently featured message from overlay WebSocket/HTTP
Next in Queue Displays the next queued message WebSocket/HTTP
Toggle Auto-Show Enables/disables automatic message featuring WebSocket/HTTP
Send Chat Message Sends a message to all connected platforms WebSocket/HTTP

Dynamic Variables

  • featured_message - Current featured message text
  • featured_username - Current featured username
  • queue_size - Number of messages in queue

Setup Resources

Get Companion Module Documentation

AI Integration

AI Chat Bot Mode

Social Stream Ninja provides comprehensive AI integration to enhance your streams with AI-powered chat responses, moderation, and more. Choose from local or cloud-based AI providers to match your needs.

Automated Chat Responses

Let the AI engage with your viewers automatically, answering questions and keeping the conversation lively even when you're focused on your content.

Content Moderation

Use AI to help moderate chat by identifying potentially harmful messages and automatically handling them based on your preferences. Choose between non-blocking or strict blocking modes.

RAG Search

Retrieval-Augmented Generation allows the AI to search through your custom knowledge base to provide accurate answers specific to your content.

Multiple Bot Instances

Run different bot instances for various purposes: public chat bot, private 1-on-1 bot, censor bot, and even a multimodal AI co-host that can see and hear.

Supported AI Providers

Social Stream Ninja supports multiple AI providers, from fully local browser/runtime models to hosted APIs:

Ollama (Native Local API)

Free, privacy-focused, self-hosted AI models running on your own computer through Ollama's own API.

Local Gemma 4

Run Gemma 4 in the browser using self-hosted model assets instead of a remote API.

Local Qwen 3.5

Run Qwen 3.5 in the browser from your own hosted model files for local, private responses.

ChatGPT / OpenAI

OpenAI APIs including modern chat and realtime voice models.

Google Gemini

Google Gemini models including current Gemini 2.5 text and live multimodal options.

DeepSeek

Efficient, cost-effective AI models optimized for conversational tasks.

xAI (Grok)

xAI Grok APIs, including realtime voice sessions when using ephemeral client secrets.

AWS Bedrock

Enterprise-grade AI models from various providers including Claude and Llama.

OpenRouter

Access to multiple AI models through a unified API interface.

Groq

Low-latency OpenAI-compatible chat inference for fast conversational responses.

Custom API (OpenAI-compatible)

Connect to llama.cpp, LM Studio, vLLM, or any other OpenAI-compatible endpoint.

Note: Ollama uses its own native API. For llama.cpp, LM Studio, vLLM, or other OpenAI-compatible servers, choose Custom API.

Text-to-Speech Integration

Social Stream Ninja includes comprehensive TTS support for bot messages and featured chat content:

System TTS

Free, built-in TTS using your operating system's voice synthesizer.

Kokoro

Free, locally-running TTS using WebGPU/CPU for privacy-conscious users.

Kitten TTS

Lightweight browser-based TTS that downloads a small model for local voice generation.

ElevenLabs

Premium voice synthesis with natural-sounding, customizable voices.

Google Cloud TTS

High-quality voices with extensive language and customization options.

Gemini (Preview TTS)

Google's preview neural voice models with selectable voice and language options.

Speechify

AI-powered text-to-speech with natural voice conversion capabilities.

OpenAI TTS

OpenAI speech synthesis with selectable voices, models, and optional compatible endpoints.

Note: TTS functionality requires the appropriate overlay page to be open in OBS. Each TTS provider offers different voice options, latency, and pricing or hardware requirements.

Bot Instances and Overlays

Social Stream Ninja provides multiple bot instances for different use cases:

Bot Type URL Description
Primary Chat Bot /bot.html Main bot overlay with optional TTS and public chat responses
Private Chat Interface /chatbot.html Dedicated 1-on-1 bot page that does not share the main bot's RAG dataset or chat history
Censor Bot (runs in background) Filters, sanitizes, or blocks incoming messages automatically
AI Co-Host /cohost.html Multimodal AI that can see your screen, hear audio, and interact

Setting Up AI Integration

Follow these steps to set up AI integration with the current menu:

1

Choose and Connect Your LLM Provider

Select your provider in Configure LLM Service Provider and fill in the matching fields:

  • Ollama: Install locally and set the endpoint if needed
  • Local Gemma / Local Qwen: Self-host the browser model assets and optional model folder override
  • ChatGPT, Gemini, DeepSeek, xAI, Groq, OpenRouter, Bedrock: Add your API key and preferred model
  • Custom API: Enter an OpenAI-compatible endpoint, model id, and optional API key
2

Test the Selected Chat Bot

Use the built-in Test selected chat bot button to verify your provider, model, and credentials before going live.

3

Configure Bot Behavior

Customize how the bot behaves in chat:

  • Enable the LLM AI chat bot
  • Set the bot name, trigger words, and response rate limit
  • Choose whether replies go back to chat or only to the bot overlay page
  • Add custom instructions for tone, role, and moderation rules
4

Enable Optional Extras

Turn on the features you want around the bot:

  • Enable TTS for bot replies and choose a provider
  • Enable RAG and upload documents for knowledge-aware answers
  • Enable the censor bot for moderation or strict block mode
  • Open /bot.html, /chatbot.html, or /cohost.html in OBS or a browser as needed

Detailed Documentation

For complete setup instructions and deeper TTS coverage, use these guides:

Complete AI Integration Guide Local AI TTS Guide AI Setup Documentation on GitHub

MIDI & Hotkey Control

MIDI Integration

Control Social Stream Ninja using MIDI controllers, keyboard shortcuts, or StreamDeck with MIDI plugins.

Setup Requirements

  1. Enable MIDI support in the extension settings
  2. Install a virtual MIDI loopback device (e.g., loopMIDI)
  3. Configure your MIDI controller or StreamDeck MIDI plugin
CC Number Value Action Notes
102 1 Send "1" to chat Quick reaction
102 2 Send "LUL" to chat Emote reaction
102 3 Tell a joke Triggers bot response
102 4 Clear overlay Removes featured message

Tip: MIDI control works best with physical controllers but can also be triggered via virtual MIDI devices.

Hotkey Support

Use keyboard shortcuts for quick access to common functions.

Hotkeys can be configured within the menu settings and work system-wide when the browser is focused or when the app is used.

Webhook Integration

Donation Services

Social Stream Ninja can receive donations and events from third-party services via webhooks; a few popular ones are below:

Stripe

Stripe

Process credit card donations directly through your Stripe account.

  • Create a payment link at stripe.com
  • In Stripe Dashboard, go to Developers → Webhooks
  • Add endpoint: https://io.socialstream.ninja/SESSIONID/stripe
  • Select the event checkout.session.completed
  • Add &server to your dock URL
Ko-Fi

Ko-Fi

Receive coffee donations from your supporters.

  • Sign in to your Ko-Fi account
  • Go to Webhook settings
  • Add https://io.socialstream.ninja/SESSIONID/kofi as the webhook URL
  • Add &server to your dock URL
  • Test with the "Send Single Donation Test" button
Buy Me A Coffee

Buy Me A Coffee

Collect donations through the popular Buy Me A Coffee platform.

  • Sign in to your Buy Me A Coffee account
  • Navigate to webhook settings
  • Add https://io.socialstream.ninja/SESSIONID/bmac as the webhook URL
  • Add &server to your dock URL to receive events
  • Both donations and membership events are supported

Security Note: Keep your session ID private, as anyone with it can send fake donations to your overlay. The webhook URL should be treated as sensitive information.

External Service Integration

Social Stream Ninja can also send data to third-party services:

Service URL Parameter Description
Singular Live &singular=IDENTIFIER Sends selected messages to Singular Live for featured message overlay
H2R &h2r=IDENTIFIER Sends selected messages to a local H2R server
Generic POST &postserver=URL Sends selected messages to a custom endpoint via POST
Generic PUT &putserver=URL Sends selected messages to a custom endpoint via PUT

These parameters should be added to the dock page URL.

Custom Scripts

Custom JavaScript

You can create your own commands and functionality by customizing the JavaScript code:

Using custom.js

  1. Rename custom_sample.js to custom.js
  2. Edit the file to add your custom functionality
  3. Open the dock.html file locally for the custom.js to be loaded

This method allows for complex customizations and triggers.

Custom Overlays

Creating Custom Overlays

You can create completely custom chat overlays from scratch to match your stream's unique style and functino. Social Stream Ninja provides a flexible foundation that you can build upon.

Starting with a Template

Begin with our sample overlay template to understand the basics:

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

This minimal template includes just the essential code needed for a functioning overlay.

View Sample Overlay

Key Features to Customize

  • Toggle between featured messages or showing all messages
  • Customize the appearance with CSS
  • Add custom animations for new messages
  • Implement your own message filtering
  • Add interactive elements with JavaScript

Implementation Steps

  1. Download the sample overlay HTML file
  2. Edit the HTML for your custom layout
  3. Customize the CSS for your desired appearance
  4. Modify the JavaScript as needed for custom behaviors
  5. Save the file locally to use in OBS as a browser source

Timer API

Control timer.html Remotely

The timer page is intentionally narrow in scope: one timer, optional operator controls, warning states, overtime, and a few visual styles.

Useful actions include starttimer, pausetimer, resettimer, timeradd, timersubtract, and settimer.

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

To query the current timer state, use gettimerstate with a callback token.

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

Use the page with timer.html?session=YOUR_SESSION&server if you want it controlled directly through the API server.

Ready to Take Your Stream to the Next Level?

With these powerful commands and API options, you can create a truly unique and interactive streaming experience.

Download Now Get Support