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.

Important: You must enable the Server API toggle in the extension menu for API functionality to work.

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.

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 control:

	- Channel 1: Main communication channel (default)
	- Channel 2: Typically used for dock.html communication
	- Channel 3: Often used for extension communication
	- Channel 4: Commonly used for featured.html communication
	- Channel 5: Used for waitlist.html communication
	- Channels 6-9: Reserved for future use

You can specify input and output channels when connecting:

wss://io.socialstream.ninja/join/SESSION_ID/IN_CHANNEL/OUT_CHANNEL

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 service providers, giving you flexibility in choosing the right solution for your stream:

Ollama (Local)

Free, privacy-focused, self-hosted AI models running on your own computer.

ChatGPT

OpenAI's powerful chat models via API key integration (gpt-4, gpt-3.5-turbo).

Google Gemini

Google's multimodal AI models including Gemini Pro and Gemini Flash.

DeepSeek

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

xAI (Grok)

Elon Musk's xAI models offering unique perspectives and real-time information.

AWS Bedrock

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

OpenRouter

Access to multiple AI models through a unified API interface.

Custom API

Connect to any OpenAI-compatible endpoint for maximum flexibility.

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.

ElevenLabs

Premium voice synthesis with natural-sounding, customizable voices.

Google Cloud TTS

High-quality voices with extensive language and customization options.

Speechify

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

Kokoro

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

Note: TTS functionality requires the appropriate overlay page to be open in OBS. Each TTS provider offers different voice options, quality levels, and pricing models.

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 TTS support, responds to chat and displays messages
Private Chat Interface /chatbot.html Standalone 1-on-1 interface for private conversations with the AI
Censor Bot (runs in background) Filters and moderates 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 your preferred provider:

1

Choose Your AI Provider

Select from the supported providers in the extension settings. Each provider requires different setup:

  • Ollama: Install locally and set up CORS
  • ChatGPT/Gemini/etc: Add your API key
  • Custom: Configure your endpoint URL
2

Configure Bot Settings

Customize your bot behavior:

  • Set trigger words or allow all responses
  • Enable/disable context memory
  • Configure rate limiting
  • Choose moderation level
  • Set custom instructions
3

Set Up TTS (Optional)

Choose your TTS provider and configure voice settings:

  • Select voice language and style
  • Adjust speed, pitch, and volume
  • Configure URL and name reading preferences
  • Set up audio routing options
4

Add Knowledge Base (Optional)

Upload files for RAG (Retrieval-Augmented Generation):

  • Add text files or markdown
  • Enable enhanced processing for better results
  • Manage and update your knowledge database

Detailed Documentation

For complete setup instructions and advanced configuration options, see our detailed guides:

Complete AI Integration 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:

Method 1: custom.js File

  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.

Method 2: URL Parameter

Inject JavaScript directly via URL parameter:

&js=URL_ENCODED_JAVASCRIPT

Example:

https://socialstream.ninja/featured.html?session=SESSIONID&js=https%3A%2F%2Fexample.com%2Fcustom.js

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

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