Social Stream Ninja API Documentation

The API allows real-time, bidirectional communication between your application and the Social Stream Ninja extension/app, the dock page, and the overlay pages.

There is an easy to use sandbox to play with some of the common API commands and options over here.

Capability-driven control clients should use the versioned Social Stream Remote-Control Protocol. The legacy commands documented below remain supported.

Table of Contents

WebSocket API
HTTP API
Special Pages and Features
Message Targeting System
- How it works
- Use Cases
Best Practices
Inbound Donation Webhooks
Featured Page (featured.html)
Dock Page (dock.html)
Social Stream Ninja API Documentation
Extension
Waitlist Page (waitlist.html)
Battle royale, Polls, etc
StreamDeck Integration Guide for Social Stream Ninja
Using Bitfocus Companion with Social Stream Ninja

WebSocket API

The WebSocket API allows real-time, bidirectional communication between your application and the Social Stream Ninja server.

If you prefer to keep traffic peer-to-peer without enabling the WebSocket relay, you can instead integrate the Social Stream Ninja WebRTC SDK. It offers a Node- and browser-friendly interface that plugs into the same transport layer used by the extension. A Social Stream Ninja listener example is available at ninjasdk/demos/socialstreamninja-listener.js.

Choose Your Use Case

There are two main reasons to use the WebSocket API:

Use Case	What You Want	Required Toggle(s)	Channel
Remote Control	Send commands to SSN (clear, feature, next in queue, send chat) from StreamDeck, Bitfocus Companion, or custom apps	✅ Enable remote API control	Channel 1 (default)
Chat Listener	Receive chat messages from Twitch/YouTube/etc. in your Python/Node app	✅ Enable remote API control + ✅ Send chat messages to API server (3rd toggle)	Channel 4

Toggle Reference (Global settings > Mechanics):

Toggle	Purpose
1. Enable remote API control of extension	Required for ALL API usage. Allows sending commands to the extension.
2. Enable Dock to use and publish via API server	Needed to send commands directly to the Dock page (clear, nextInQueue, etc.)
3. Send chat messages to API server	Required to RECEIVE chat messages! Routes Twitch/YouTube/etc. chat through the server on channel 4.
4. Dock sends its commands to Extension via server	Optional. Allows Dock to send commands back to extension via server instead of P2P.

Quick Start: Remote Control (StreamDeck / Bitfocus Companion)

For controlling SSN from StreamDeck, Bitfocus Companion, or similar tools, you only need the first toggle enabled.

Simple HTTP GET request:

https://io.socialstream.ninja/SESSION_ID/nextInQueue
https://io.socialstream.ninja/SESSION_ID/clearOverlay
https://io.socialstream.ninja/SESSION_ID/clearBotOverlay
https://io.socialstream.ninja/SESSION_ID/sendEncodedChat/null/Hello%20World
https://io.socialstream.ninja/SESSION_ID/drawmode/null/toggle

WebSocket commands:

ws = new WebSocket("wss://io.socialstream.ninja/join/SESSION_ID");
ws.onopen = () => {
    // Send a command
    ws.send(JSON.stringify({ action: "nextInQueue" }));
    ws.send(JSON.stringify({ action: "clearOverlay" }));
    ws.send(JSON.stringify({ action: "clearBotOverlay" }));
    ws.send(JSON.stringify({ action: "sendChat", value: "Hello from API!" }));
};

See the StreamDeck Integration Guide and Bitfocus Companion sections below for detailed setup.

Quick Start: Receiving Chat Messages (Python / Node.js)

To receive chat messages from Twitch, YouTube, and other platforms in your own application:

Required toggles (Global settings > Mechanics):

✅ Enable remote API control of extension
✅ Send chat messages to API server (the 3rd toggle) - This is the key one!

Connect to Channel 4 - This is where chat messages are broadcast:

Python Example:

import asyncio
import websockets
import json

SESSION_ID = "YOUR_SESSION_ID_HERE"  # From your dock.html URL

async def listen_to_chat():
    uri = f"wss://io.socialstream.ninja/join/{SESSION_ID}/4"  # Channel 4 receives chat

    async with websockets.connect(uri) as ws:
        print(f"Connected! Listening for chat messages...")

        while True:
            message = await ws.recv()
            data = json.loads(message)

            # Chat messages have 'chatname' and 'chatmessage' fields
            if "chatname" in data:
                print(f"[{data.get('type', 'unknown')}] {data['chatname']}: {data.get('chatmessage', '')}")

                # Check for donations
                if data.get('hasDonation'):
                    print(f"  💰 Donation: {data['hasDonation']}")

asyncio.run(listen_to_chat())

Node.js Example:

const WebSocket = require('ws');

const SESSION_ID = 'YOUR_SESSION_ID_HERE';  // From your dock.html URL

const ws = new WebSocket(`wss://io.socialstream.ninja/join/${SESSION_ID}/4`);

ws.on('open', () => {
    console.log('Connected! Listening for chat messages...');
});

ws.on('message', (message) => {
    const data = JSON.parse(message);

    // Chat messages have 'chatname' and 'chatmessage' fields
    if (data.chatname) {
        console.log(`[${data.type || 'unknown'}] ${data.chatname}: ${data.chatmessage || ''}`);

        // Check for donations
        if (data.hasDonation) {
            console.log(`  💰 Donation: ${data.hasDonation}`);
        }
    }
});

ws.on('error', console.error);

Channel Reference for Listeners:

Channel 4 (/join/SESSION/4) - Receives chat messages from the extension (when "Send chat messages to API server" is enabled)
Channel 2 (/join/SESSION/2) - Receives messages from the Dock (when "Enable Dock to use and publish via API server" is enabled)

Connecting to the API Server

Connect to the WebSocket server at wss://io.socialstream.ninja.

There are two methods to connect and join a session:

Direct connection with parameters:

ws = new WebSocket("wss://io.socialstream.ninja/join/SESSION_ID/IN_CHANNEL/OUT_CHANNEL");

Connect first, then send a join message:

ws = new WebSocket("wss://io.socialstream.ninja");
ws.onopen = function() {   
    ws.send(JSON.stringify({ join: "SESSION_ID", in: IN_CHANNEL, out: OUT_CHANNEL }));
};

Parameters:

SESSION_ID: Your unique session identifier (same as used in dock.html or featured.html URL)
IN_CHANNEL: Channel number to receive messages (optional)
OUT_CHANNEL: Channel number to send messages (optional)

The default channel value is used if not specified

Channel System Explained

The channel system allows for more granular control over message routing:

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
Channel 6: Reserved for future use
Channel 7: Reserved for future use
Channel 8: Reserved for future use
Channel 9: Reserved for future use

When specifying channels, you're defining which channels to receive messages from (IN_CHANNEL) and which to send messages to (OUT_CHANNEL). This allows different components of your setup to communicate on separate channels, reducing noise and improving organization.

When a message is sent, it goes to the specified output channel. Those who have that channel set as their input channel will receive the message.

Available Commands

Send Chat Message
- Action: sendChat
- Example: {"action": "sendChat", "value": "Hello, world!"}
Send Encoded Chat Message
- Action: sendEncodedChat
- Example: {"action": "sendEncodedChat", "value": "Hello%2C%20world%21"}
Block User
- Action: blockUser
- Example: {"action": "blockUser", "value": {"chatname": "username", "type": "twitch"}}
Send External Content
- Action: extContent
- Example: {"action": "extContent", "value": "{\"chatname\":\"User\",\"chatmessage\":\"Hello\"}"}
Waitlist Operations
- Remove the first active entry: {"action": "removefromwaitlist", "value": 1}
- Highlight an active entry: {"action": "highlightwaitlist", "value": 2}
- Reset: {"action": "resetwaitlist"}
- Stop accepting new entries: {"action": "stopentries"}
- Start accepting new entries again: {"action": "startentries"}
- Set the waitlist/draw title message: {"action": "waitlistmessage", "value": "Type !join to enter!"}
- Download: {"action": "downloadwaitlist"}
- Select winners: {"action": "selectwinner", "value": 1}
Leaderboard Operations
- Reset open leaderboard overlays: {"action": "resetleaderboard"}
Clear Messages
- Dock: {"action": "clearDock"} (clear and clearAll remain supported aliases)
- A dock with &sync also clears its synced docks. Without &sync, only the targeted dock clears.
- Target a labeled dock with {"action": "clearDock", "target": "producer"} and &label=producer on that dock URL.
- Permanently delete saved history: {"action": "clearHistory", "value": {"confirm": true}}
- Overlay: {"action": "clearOverlay"}
Queue Operations
- Next: {"action": "nextInQueue"}
- Get Size: {"action": "getQueueSize"}
Auto-show Toggle
- {"action": "autoShow", "value": "toggle"}
Feature Next Message

{"action": "feature"}

Get Chat Sources

{"action": "getChatSources"}

VIP User Operations

Toggle: {"action": "toggleVIPUser", "value": {"chatname": "username", "type": "twitch"}}

Get User History

{"action": "getUserHistory", "value": {"chatname": "username", "type": "twitch"}}

Draw Mode

{"action": "drawmode", "value": true}
{"action": "drawmode", "value": "toggle"}

Emote-only Filter

Toggle or set the global emote-only mode that keeps only emotes/emoji from chat messages. Messages that become empty (and have no donation/content image) after filtering are dropped.
Examples:
- {"action": "emoteonly", "value": "toggle"}
- {"action": "emoteonly", "value": true}
- {"action": "emoteonly", "value": false}

Poll Operations
- Reset: {"action": "resetpoll"}
- Close: {"action": "closepoll"}
- Load Preset: {"action": "loadpoll", "value": {"pollId": "poll-123456"}}
- Set Settings: {"action": "setpollsettings", "value": {"pollQuestion": "What's your favorite color?", "pollType": "multiple", "multipleChoiceOptions": "Red\nBlue\nGreen"}}
- Get Presets: {"action": "getpollpresets"}
- Create New: {"action": "createpoll", "value": {"settings": {"pollQuestion": "New Poll", "pollType": "freeform"}}}

Channel-Specific Messaging

You can send messages to specific channels using the content action with a channel number:

Channel 1: {"action": "content", ...}
Channel 2: {"action": "content2", ...}
Channel 3: {"action": "content3", ...}
Channel 4: {"action": "content4", ...}
Channel 5: {"action": "content5", ...}
Channel 6: {"action": "content6", ...}
Channel 7: {"action": "content7", ...}

HTTP API

The server also supports HTTP GET, POST, and PUT requests for the same actions. Replace SESSION_ID with your actual session ID.

GET: https://io.socialstream.ninja/SESSION_ID/ACTION/TARGET/VALUE
POST/PUT: https://io.socialstream.ninja/SESSION_ID (with JSON body)
POST/PUT: https://io.socialstream.ninja/SESSION_ID/ACTION (with JSON body)

If your action needs a value but no target, use null as the target placeholder:

https://io.socialstream.ninja/SESSION_ID/drawmode/null/true
https://io.socialstream.ninja/SESSION_ID/drawmode/null/toggle

Channel Parameter

You can specify the output channel for HTTP requests using the channel query parameter:

https://io.socialstream.ninja/SESSION_ID/ACTION/TARGET/VALUE?channel=2

This will send the message to channel 2. If not specified, it defaults to channel 1.

Server-Sent Events (SSE)

Connect to the SSE endpoint to receive real-time updates:

const eventSource = new EventSource(`https://io.socialstream.ninja/sse/SESSION_ID`);

There is a demo overlay that uses SSE here: https://socialstream.ninja/tests/sse.html

Receiving Responses

Include a get parameter in your request for actions that require a response:

{
  "action": "yourAction",
  "value": "yourValue",
  "get": "uniqueIdentifier"
}

The server will respond with:

{
  "callback": {
    "get": "uniqueIdentifier",
    "result": true
  }
}

Note: Not all commands support or require this callback mechanism.

Response Types

Success: The server will typically respond with the result of the action.
Failed: If the action couldn't be performed (e.g., no clients connected to the specified room), the server responds with "failed".
Timeout: If the server doesn't receive a response from the clients within 5 seconds, it responds with "timeout".
Special: For non-default channels (2-7), if no clients are connected, the server responds with "special" instead of "failed".

Special Pages and Features

Emotes Page (emotes.html)
- Displays emojis/emotes/icons dancing on the screen
- Can receive content via WebRTC or the WebSocket API
- To send content via API: Use the content action on channel 1
Waitlist Page (waitlist.html)
- Manages draws and waitlists for giveaways
- Communicates on channel 5
- Supports actions like selecting winners and managing the waitlist
Custom Actions
- Create custom auto-responding triggers or actions using a custom.js file
- Example: auto1 trigger responds "1" to any message that is "1"
Queuing and Pinning Messages
- Queue: Hold CTRL (cmd on Mac) and click messages in the dock
- Pin: Hold ALT and click messages to pin them at the top
- API pin existing row: {"action":"pin","value":"MESSAGE_MID"}
- API pin by full message object: {"action":"pin","value":{"id":"external-1","chatname":"User","chatmessage":"Pinned note","type":"api"}}
- API unpin row: {"action":"unpin","value":"MESSAGE_MID"}
- API feature the first pinned row: {"action":"nextPinned"}
- Existing dock sync payloads are still supported: {"pin":["MESSAGE_MID"]} and {"unpin":["MESSAGE_MID"]}
Pinning is handled by dock.html, so a dock must be open on the same session. If you have multiple docks, use a dock label and target it:
```
{"action":"pin","target":"moderator-dock","value":"MESSAGE_MID"}
{"action":"unpin","target":"moderator-dock","value":"MESSAGE_MID"}
{"action":"nextPinned","target":"moderator-dock"}
```
HTTP GET examples:
```
https://io.socialstream.ninja/SESSION_ID/pin/null/MESSAGE_MID
https://io.socialstream.ninja/SESSION_ID/unpin/null/MESSAGE_MID
https://io.socialstream.ninja/SESSION_ID/nextPinned
https://io.socialstream.ninja/SESSION_ID/pin/moderator-dock/MESSAGE_MID
```
MIDI Hotkey Support
- Toggle in the extension menu
- Allows predefined chat messages to be sent to all social destinations
- MIDI actions available on Control Change channel 1

Message Targeting System

Social Stream Ninja implements a targeting system that allows messages to be directed to specific instances of the dock or featured pages if multiple of either are open.

How it works

URL Parameter: Each instance (featured/dock) can be given a unique label using the label URL parameter.

Example: featured.html?label=stream1 or dock.html?label=controlpanel1
Message Structure: When sending a message through the API, include a target field with the label of the intended recipient.

Example:
```
{
  "action": "someAction",
  "target": "stream1",
  "value": "someValue"
}
```
Message Processing: The application checks each incoming message for a target. If the message has a target that doesn't match the instance's label, the message is ignored.

Use Cases

Running multiple streams with different configurations
Sending commands to specific control panels
Updating particular displays without affecting others

This targeting system allows for more flexible and powerful setups, especially in complex streaming environments.

Best Practices

Always handle potential errors and timeouts in your application.
Use appropriate channels for different types of messages to keep your communication organized.
Leverage the targeting system when working with multiple instances to ensure messages reach the intended recipients.
Regularly check for updates to the API as new features may be added over time.

Inbound Donation Webhooks

Social Stream Ninja can receive donation events from external platforms via webhooks. These donations appear in your dock and overlays alongside regular chat messages.

Prerequisites

Note Your Session ID: Find it in the extension popup or in your URL after ?session=.
Keep Social Stream Ninja enabled.
Under Global settings and tools → Mechanics, enable remote API control of extension. This lets background.js receive and normalize inbound webhooks before sending them through the normal message path.
Use your normal generated dock and overlay links. Do not manually add &server, &server2, or &server3 for donation webhooks.
If the dock was already open when you enabled the setting, reload it once.

This is the only API toggle required for inbound donation webhooks. The other API transport toggles serve different workflows and can remain off.

With this route, each donation is normalized once in the extension and then delivered like a regular Social Stream message to chat, alerts, Event Flow, and the Tip Jar/Goal Meter.

Supported Platforms

Platform	Webhook URL	Event Type
Stripe	`https://io.socialstream.ninja/{sessionID}/stripe`	`checkout.session.completed`
Ko-Fi	`https://io.socialstream.ninja/{sessionID}/kofi`	Donations (public only)
Buy Me A Coffee	`https://io.socialstream.ninja/{sessionID}/bmac`	`donation.created`, `membership.started`
Fourthwall	`https://io.socialstream.ninja/{sessionID}/fourthwall`	`ORDER_PLACED`

Stripe Setup

Create a Stripe Payment Link
Important: Add custom fields to your payment link:
- Display Name or Username (required) - donations without this field are rejected
- Message (optional) - allows donors to leave a message
Go to Stripe Webhooks and create a new endpoint
Set the URL to: https://io.socialstream.ninja/YOUR_SESSION_ID/stripe
Select event: checkout.session.completed
No signature verification is needed (keep your session ID private instead)

Testing: Use Stripe's Test Mode with card number 4242 4242 4242 4242, any future expiry date, and any CVC.

Ko-Fi Setup

Sign in to Ko-Fi Webhook Settings
Paste https://io.socialstream.ninja/YOUR_SESSION_ID/kofi into Webhook URL, then click Update
Enable remote API control of extension as shown above
Reload an already-open dock, then click Send single tip test in Ko-Fi
Confirm exactly one alert appears; only public donations are supported

Buy Me A Coffee Setup

Sign in to Buy Me A Coffee and navigate to Settings → Webhooks
Add webhook URL: https://io.socialstream.ninja/YOUR_SESSION_ID/bmac
Both one-time donations (donation.created) and new memberships (membership.started) are supported

Fourthwall Setup

Go to your Fourthwall admin: Settings → For Developers → Webhooks
Create a webhook with URL: https://io.socialstream.ninja/YOUR_SESSION_ID/fourthwall
Subscribe to ORDER_PLACED events

Security Note

Keep your session ID private. Anyone with your session ID can send fake donation events to your overlay. The webhook URLs do not use signature verification, so security relies on the secrecy of your session ID.

Donation Message Format

When a donation webhook is received, it is normalized into a standard SSN message format:

{
  "chatname": "Donor Name",
  "chatmessage": "Optional message from donor",
  "hasDonation": "$50.00 USD",
  "type": "stripe",
  "id": "unique_id",
  "meta": {
    "webhookId": "provider_delivery_id"
  },
  "chatbadges": "",
  "chatimg": "",
  "membership": ""
}

The hasDonation field contains the formatted amount and currency. meta.webhookId preserves the provider's stable event identifier for retry and mixed-transport deduplication. This allows donations to be filtered, featured, and displayed using the same mechanisms as platform-native donations (Super Chats, Bits, etc.).

Featured Page (featured.html)

The featured.html page is designed to display featured content, typically used for showcasing selected messages or donations in a stream overlay. It communicates primarily on channel 3 for output and channels 1 and 2 for input, depending on the configuration.

Connection Options

The featured.html page can be configured to connect to the WebSocket server in three different ways:

Default (server): Connects to wss://io.socialstream.ninja, joins the room, and sets output to channel 3 and input to channel 2.
Server2: Sets output to channel 3 and input to channel 4.
Server3: Sets output to channel 3 and input to channel 1.

In all cases, channel 3 is reserved for output from the featured.html page.

These can be set using URL parameters:

?server: Default connection
?server2: Server2 connection
?server3: Server3 connection

Content Filtering Options

The featured page offers several filtering options that can be controlled via the API:

onlyshowdonos: Only show messages with donations
hideDonations: Hide donation information
hideevents: Hide all event payloads that include an event type
filterevents: Hide specific events by exact event name or matching event text
hideTwitch: Hide messages from Twitch
onlyTwitch: Only show messages from Twitch
onlyFrom: Only show messages from a specific source
hideFrom: Hide messages from specific sources
filterfeaturedusers: Only show messages from approved listed users

API Actions

The featured page responds to the following API actions:

content: Display new content
- Example: {"action": "content", "value": {...contentObject...}}
clear: Clear the currently displayed content
- Example: {"action": "clear"}
toggleTTS or tts: Toggle or set Text-to-Speech
- Example: {"action": "toggleTTS", "value": "toggle"} or {"action": "tts", "value": "on"}

Content Object Structure

When sending content to be displayed, the content object should have the following structure:

{
  "chatname": "Username",
  "chatmessage": "Message content",
  "chatimg": "URL to user avatar",
  "contentimg": "URL to content image",
  "subtitle": "Subtitle text",
  "membership": "Membership information",
  "hasDonation": "Donation information",
  "type": "Source type (e.g., twitch, youtube)",
  "id": "Unique message ID"
}

chatname, chatmessage, and type tend to be the most important.

A full breakdown of different keys though used in SSN are the following:

key name	value type	description
chatname	string	Display name that will be rendered in overlays.
chatmessage	string (HTML permitted)	Message body; can contain sanitized HTML/emote markup when `textonly` is false.
chatimg	string (URL or data URI <= 55 KB)	Author avatar. Absolute URLs preferred; legacy data URIs remain supported.
type	string (lowercase identifier)	Primary source identifier such as `twitch`, `youtube`, `kick`. Also used to resolve the default icon `https://socialstream.ninja/sources/images/{type}.png`.
sourceImg	string (URL or `./sources/images/...`)	Optional alternate icon representing a sub-source (ex: channel avatar, Restream origin). Should generally differ from the `type` icon. Legacy relative paths are normalised to `./sources/images/{file}` for consistency but remain locally resolved.
sourceName	string	Channel title, profile name, or host identifier associated with the source feed.
textonly	boolean	Applies only to `chatmessage`; indicates whether `chatmessage` should be treated as plain text (`true`) or may contain markup (`false`). Other normal fields are expected to be plain text, except media fields such as `chatimg` and `contentimg`.
hasDonation	string	Donation amount with units, e.g., `"3 roses"` or `"$50 USD"`.
chatbadges	Array<string \| BadgeDescriptor>	Badge icons shown beside the author. Strings are image URLs; `BadgeDescriptor` objects can include `{ type, text, src }` for richer badges.
contentimg	string (URL)	Optional media attachment for the message (image/gif/mp4/webm).
membership	string	Short description of a membership/subscription state or label (e.g., `"Member"` or `"Tier 3 Upgrade"`).
title	string	Display title for donations or other highlighted events (defaults like `"CHEERS"` or `"DONATION"` are common).
subtitle	string	Additional detail for memberships or donations (e.g., `"12 months"` or `"Gifted by Alex"`).
moderator	boolean	Marks the author as a moderator for the source platform.
event	string \| boolean	Identifies structured events (`"follow"`, `"raid"`, etc.) or `false`/omitted when the message is standard chat.
admin	boolean	Flags elevated/privileged accounts.
bot	boolean	Flags automated or host-generated messages.
question	boolean	Indicates the message has been classified as a question.
userid	string	Stable user identifier from the source platform (helpful for API lookups, blocking, etc.).
karma	number (0.0–1.0)	Sentiment score; `1.0` positive, `0.0` negative. Provided by AI heuristics when available.
id	integer	Internal message identifier assigned by SSN for de-duplication/routing.
private	boolean	Marks direct/private messages that should not be surfaced publicly by default.
nameColor	string (CSS color)	Overrides the rendered display-name color.
textColor	string (CSS color)	Overrides the rendered message text color.
backgroundColor	string (CSS color)	Overrides the background color for highlighted message cards.
meta	object	Extra structured data that doesn't fit elsewhere (viewer counts, membership details, `eventTypeMapping`, etc.).

Additional Features

Queue System: If queuetime is set, messages are added to a queue and displayed sequentially.
Image Preloading: The page attempts to preload user avatars and source type images for smoother display.
IFrame Support: The page can adjust its height when embedded in an IFrame.
Transition Effects: Content transitions can be customized using CSS classes.

Best Practices and Improvements

Error Handling: Implement more robust error handling for WebSocket connections and message parsing.
Configuration Options: Consider adding more configuration options via URL parameters or API calls to control filtering and display behavior.
Performance Optimization: For high-traffic streams, implement rate limiting or batching of messages to prevent overwhelming the display.
Accessibility: Add options for controlling text size, contrast, and display duration to improve readability for viewers.
Analytics: Implement tracking for displayed messages and user interactions to gather insights on engagement.

Example API Usage

To display a new featured message:

socketserver.send(JSON.stringify({
  action: "content",
  value: {
    chatname: "ExampleUser",
    chatmessage: "Hello, featured chat!",
    type: "twitch",
    hasDonation: "$5.00"
  }
}));

To clear the current featured message:

socketserver.send(JSON.stringify({ action: "clear" }));

To toggle Text-to-Speech:

socketserver.send(JSON.stringify({ action: "toggleTTS", value: "toggle" }));

Dock Page (dock.html)

The dock.html page serves as a control center for managing chat messages and interactions. It connects to multiple WebSocket servers and processes incoming messages.

Connection Options

The dock page can be configured to connect to different WebSocket servers:

Main Server (default):
- URL: wss://io.socialstream.ninja/api
- Configurable via the server URL parameter
- Joins room with out: 2, in: 1
Extension Server:
- URL: wss://io.socialstream.ninja/extension
- Configurable via the server2 or server3 URL parameters
- Joins room with out: 3, in: 4

URL Parameters

server: Sets the main server URL
server2: Enables connection to the extension server and sets its URL
server3: Enables connection to both main and extension servers

WebSocket Message Processing

The dock page processes incoming WebSocket messages using the processInput function. This function handles various types of messages and actions, including:

Message management (pin, unpin, queue)
User actions (block, delete messages)
Content display and filtering
Chat source management
User history retrieval
Payment processing (Stripe, Ko-fi, Buy Me a Coffee)
OBS commands
TTS (Text-to-Speech) control

Key Features

Message Queue: Manages a queue of messages for display
Pinned Messages: Allows pinning and unpinning of messages
User Blocking: Supports blocking users across different platforms
Content Filtering: Provides options to filter content based on various criteria
Payment Integration: Processes donations from Stripe, Ko-fi, and Buy Me a Coffee
OBS Integration: Allows control of OBS scenes
TTS Control: Enables toggling and control of Text-to-Speech functionality

API Actions

The dock page responds to various API actions, including:

clearDock (clear and clearAll are aliases): Clears dock messages except pinned ones; &sync propagates the clear.
clearHistory: Permanently deletes the local message database when value.confirm is true or value is "confirm".
clearOverlay: Clears the overlay without affecting the dock
clearBotOverlay: Clears the Primary Chat Bot's bot.html overlay without stopping active TTS
nextInQueue: Moves to the next message in the queue
getQueueSize: Returns the current queue size
autoShow: Controls automatic message display
content: Processes and displays new content
feature: Features the next unfeatured message
pin: Pins an existing dock message by mid, or pins a full message object.
unpin: Unpins an existing dock message by mid.
nextPinned: Features the first pinned message.
toggleTTS or tts: Controls Text-to-Speech functionality

Example API Usage

To clear all messages:

socketserver.send(JSON.stringify({ action: "clear" }));

To feature the next message:

socketserver.send(JSON.stringify({ action: "feature" }));

To toggle Text-to-Speech:

socketserver.send(JSON.stringify({ action: "toggleTTS", value: "toggle" }));

Best Practices and Improvements

Error Handling: Implement more robust error handling for WebSocket connections and message parsing.
Modularization: Consider splitting the processInput function into smaller, more manageable functions for easier maintenance.
Configuration Options: Add more configuration options via URL parameters to control filtering and display behavior.
Security: Implement authentication and encryption for sensitive operations, especially those involving payment processing.
Performance Optimization: For high-traffic scenarios, implement batching of messages and more efficient DOM manipulation.
Accessibility: Add keyboard shortcuts and screen reader support for better accessibility.
Documentation: Maintain detailed inline documentation for complex functions and processes.

Social Stream Ninja API Documentation

Extension

The extension is a critical component of the Social Stream Ninja system, acting as the primary source of messages and managing communication between different parts of the system.

WebSocket Connections

The extension maintains two WebSocket connections:

Dock Connection:
- URL: wss://io.socialstream.ninja/dock
- Joins room with out: 4, in: 3
- Controlled by settings.server2 or settings.server3
API Connection:
- URL: wss://io.socialstream.ninja/api
- Joins room with out: 2, in: 1
- Controlled by settings.socketserver

Message Flow

The extension receives messages from various sources (e.g., chat platforms).
Messages are processed and can be modified by applyBotActions().
Processed messages are sent to the dock or featured pages using sendToDestinations().
Responses or user actions from the dock/featured pages are received by the extension.
The extension can then send responses back to the original platforms using processResponse().

API Actions

The extension processes various API actions, including:

sendChat: Sends a chat message to the specified destination.
sendEncodedChat: Sends an encoded chat message to the specified destination.
blockUser: Blocks a user from a specific source or all sources.
extContent: Processes external content, applying bot actions before sending.
removefromwaitlist: Removes an entry from the waitlist.
highlightwaitlist: Highlights an entry in the waitlist.
resetwaitlist: Resets the entire waitlist.
resetleaderboard: Resets open leaderboard overlays and clears their saved leaderboard state.
stopentries: Stops accepting new entries.
startentries, openentries, or resumeentries: Starts accepting new entries again.
waitlistmessage or setwaitlistmessage: Sets the waitlist/draw title message.
downloadwaitlist: Initiates a download of the waitlist.
selectwinner: Selects one or more random winners from the waitlist.
drawmode: Toggles draw mode for giveaways/waitlists.

.. and most actions that target the dock can be sent via the extension API or other overlays.

The logic in the app lets you target non-Dock overlays via the extension API using the target value, where target is the label name of the connected P2P IFRAME.

if (data.target && (data.target.toLowerCase!=="null")){
	sendTargetP2P(data, data.target);
} else {
	sendDataP2P(data);
}

Example API Usage

To send a chat message:

socketserver.send(JSON.stringify({
  action: "sendChat",
  value: "Hello, world!",
  target: "twitch" // optional, specifies the destination platform
}));

To block a user:

socketserver.send(JSON.stringify({
  action: "blockUser",
  value: "username",
  target: "youtube" // optional, "*" for all platforms
}));

To process external content:

socketserver.send(JSON.stringify({
  action: "extContent",
  value: JSON.stringify({
    chatname: "User",
    chatmessage: "Hello from an external source!",
    type: "external"
  })
}));

Best Practices and Improvements

Error Handling: Implement more robust error handling for WebSocket connections and message parsing.
Rate Limiting: Implement rate limiting to prevent flooding of messages to destinations.
Modularization: Consider splitting the message processing logic into smaller, more manageable functions.
Logging: Implement comprehensive logging for easier debugging and monitoring.
Security: Implement authentication and encryption for sensitive operations.
Configurability: Allow more fine-grained control over which actions are enabled or disabled.
Documentation: Maintain detailed inline documentation for complex functions and processes.
Testing: Implement unit and integration tests to ensure reliability of the extension.

Integration with Other Components

The extension plays a central role in the Social Stream Ninja system:

It receives messages from external chat platforms.
Processes and optionally modifies these messages.
Sends the processed messages to the dock.html or featured.html pages for display.
Receives user actions or responses from the dock/featured pages.
Can send responses back to the original chat platforms.

This central position allows the extension to act as a powerful intermediary, enabling features like chat moderation, custom bot actions, and cross-platform interactions.

Waitlist Page (waitlist.html)

The waitlist.html page is designed to manage and display waitlists or giveaways within the Social Stream Ninja system. It connects to a WebSocket server and processes incoming messages to update the waitlist display.

WebSocket Connection

URL: wss://io.socialstream.ninja/extension
Joins room with out: 5, in: 6

Key Functions

setupSocket(): Establishes and manages the WebSocket connection.
processInput(data): Processes incoming WebSocket messages and updates the waitlist display.

Waitlist Display Modes

Draw Mode: Displays entries in a draw or giveaway.
Regular Mode: Displays a standard waitlist.

Message Types and Actions

The waitlist page processes various types of messages:

waitlistmessage: Updates the waitlist title.
drawmode: Toggles draw mode and displays winners.
drawPoolSize: Updates the number of entries in the draw.
waitlist: Updates the entire waitlist display.

Key Features

Winner Selection: Displays selected winners with confetti animation.
Entry Count: Shows the number of entries in the draw.
Customizable Messages: Allows setting custom messages for the waitlist title.
Source Display: Option to show the source (e.g., Twitch, YouTube) of each entry.
Randomization: Option to randomize the order of entries in the display.

CSS Classes for Styling

.winner: Applied to winning entries.
.loser: Applied to non-winning entries in draw mode.
.selected: Applied to highlighted entries.
.guestListHolder: Container for each waitlist entry.

API Actions

The normal remote API command path controls waitlist state in the extension/app. The waitlist page then receives display payloads from that state.

Remote API actions:

{ "action": "removefromwaitlist", "value": 1 }
{ "action": "highlightwaitlist", "value": 1 }
{ "action": "resetwaitlist" }
{ "action": "stopentries" }
{ "action": "startentries" }
{ "action": "waitlistmessage", "value": "Type !join to enter!" }
{ "action": "selectwinner", "value": 1 }
{ "action": "drawmode", "value": "toggle" }

Display payloads handled by waitlist.html include:

waitlistmessage: Sets a custom message for the waitlist.

{
  "waitlistmessage": "Welcome to the giveaway!"
}

drawmode: Toggles draw mode and can display winners.

{
  "drawmode": true,
  "winlist": [
    {"chatname": "Winner1", "type": "twitch", "chatimg": "URL"},
    {"chatname": "Winner2", "type": "youtube", "chatimg": "URL"}
  ]
}

drawPoolSize: Updates the number of entries in the draw.
```
{
  "drawPoolSize": 100
}
```

waitlist: Updates the entire waitlist.

{
  "waitlist": [
    {"chatname": "User1", "type": "twitch", "chatimg": "URL", "waitStatus": 0},
    {"chatname": "User2", "type": "youtube", "chatimg": "URL", "waitStatus": 2}
  ]
}

Best Practices and Improvements

Error Handling: Implement more robust error handling for WebSocket connections and message parsing.
Performance Optimization: For large waitlists, implement virtualization or pagination to improve performance.
Accessibility: Ensure the waitlist is accessible, including keyboard navigation and screen reader support.
Customization Options: Allow more customization of the waitlist appearance through API calls or configuration options.
Animation Options: Provide options to customize or disable animations for different use cases.
Localization: Add support for multiple languages in the waitlist display.
Persistence: Implement a way to save and restore waitlist state in case of page reload or disconnection.

Integration with Other Components

The waitlist page integrates with the Social Stream Ninja system by:

Receiving waitlist updates from the extension or other components.
Displaying real-time updates of entries, winners, and draw status.
Providing a visual interface for giveaways or queue management.

This integration allows streamers or moderators to manage waitlists or giveaways efficiently while providing an engaging visual display for viewers.

Battle royale, Polls, etc

These pages may lack API support directly, however in some cases they can be controlled via the extension's API.

For example the waitlist has some functions that can be controlled via the extension:

removefromwaitlist
highlightwaitlist
resetwaitlist
stopentries
startentries
waitlistmessage
downloadwaitlist
selectwinner
drawmode

Poll Control via API

The poll system can now be controlled through the API with the following actions:

Basic Poll Controls

Reset Poll: {"action": "resetpoll"} - Resets the current poll, clearing all votes
Close Poll: {"action": "closepoll"} - Closes the current poll, preventing new votes

Advanced Poll Controls

Load Poll Preset: {"action": "loadpoll", "value": {"pollId": "poll-123456"}} - Loads a previously saved poll preset by its ID
Get Poll Presets: {"action": "getpollpresets"} - Returns a list of all saved poll presets with their IDs and names
Set Poll Settings: {"action": "setpollsettings", "value": {...}} - Updates the current poll settings
- Available settings: pollType, pollQuestion, multipleChoiceOptions, pollMatchMode, pollStyle, pollTimer, pollTimerState, pollTally, pollSpam
Create New Poll: {"action": "createpoll", "value": {"settings": {...}}} - Creates a new poll with specified settings

Example Usage

// Create a multiple choice poll
ws.send(JSON.stringify({
    action: "createpoll",
    value: {
        settings: {
            pollType: "multiple",
            pollQuestion: "What's your favorite streaming platform?",
            multipleChoiceOptions: "Twitch\nYouTube\nFacebook\nOther",
            pollTimer: "120",
            pollTimerState: true
        }
    }
}));

// Load a saved poll preset
ws.send(JSON.stringify({
    action: "loadpoll",
    value: { pollId: "poll-1234567890" }
}));

Timer Control via API

The timer page can be controlled through the API with the following actions:

Basic Timer Controls

Start Timer: {"action": "starttimer"}
Pause Timer: {"action": "pausetimer"}
Toggle Timer: {"action": "toggletimer"}
Reset Timer: {"action": "resettimer"}
Add Time: {"action": "timeradd", "value": 30} adds 30 seconds
Subtract Time: {"action": "timersubtract", "value": 30} subtracts 30 seconds

Setting Timer State

Set Timer: {"action": "settimer", "value": {...}}
- Common fields: seconds, label, mode, style, warnSeconds, dangerSeconds, soundUrl
Get Timer State: {"action": "gettimerstate", "get": "timer-123"} returns the current timer state via callback

Example Usage

// Set a 5-minute countdown named "Interview"
ws.send(JSON.stringify({
    action: "settimer",
    value: {
        seconds: 300,
        label: "Interview",
        mode: "countdown",
        style: "stage",
        warnSeconds: 60,
        dangerSeconds: 15
    }
}));

// Request current timer state
ws.send(JSON.stringify({
    action: "gettimerstate",
    get: "timer-state-1"
}));

Just to touch on the Battle Royale game though,

Battle Page (battle.html)

The battle.html page is an interactive game-like feature. Currently it doesn't use a WebSocket connection but instead communicates directly with the extension via WebRTC.

Communication Method

Uses WebRTC (peer-to-peer) for direct communication with the extension
No WebSocket server connection at the moment -- but I'll update this when it does.

Game Features

Player Join: Users can join the game using the !join command
Weapon Selection: Players can choose a weapon type when joining
In-game Chat: Players can send messages using the !say command

Message Types

startgame: Initiates the game
Content messages: Processed for game actions (join, chat)

API Actions

While the battle page doesn't directly connect to the API server, it can receive actions through the extension:

startgame: Starts the game
```
sendDataP2P({startgame: true});
```

Player join:

processData({
  chatname: "PlayerName",
  chatmessage: "!join sword",
  chatimg: "URL",
  type: "twitch",
  nameColor: "#FFFFFF"
});

In-game chat:

processData({
  chatname: "PlayerName",
  chatmessage: "!say Hello, everyone!"
});

Integration with Extension

The battle page relies on the extension for receiving data:

The extension uses sendDataP2P() to send data to the battle page
Data can be sent via WebRTC or fallback to WebSocket if available
The extension can trigger game actions like starting the game

StreamDeck Integration Guide for Social Stream Ninja

Quick Setup Method

Open StreamDeck software
Add a new "Website" action to your StreamDeck
Check GET request in background
Configure the URL using this format:

https://io.socialstream.ninja/YOUR_SESSION_ID/sendEncodedChat/null/YOUR_URL_ENCODED_MESSAGE_HERE

Replace:

YOUR_SESSION_ID with your Social Stream Ninja session ID
YOUR_MESSAGE with your URL-encoded message

For example, to send "Hello Stream!":

https://io.socialstream.ninja/abc123/sendEncodedChat/null/Hello%20Stream!

You can use this page to test and generate the correct URL here, if having problems doing it manually: https://socialstream.ninja/sampleapi.html. Note that we want to generate a GET request with this method.

Advanced Setup with Multi Actions

For more flexibility, you can use Multi Actions to send different messages:

Create a new "Multi Action" on your StreamDeck
Add "Website" actions for each command
Use these URL patterns:

WebSocket (WSS)

https://io.socialstream.ninja/YOUR_SESSION_ID/sendChat/null/YOUR_MESSAGE

HTTPS POST

https://io.socialstream.ninja/YOUR_SESSION_ID

With body:

{
    "action": "sendChat",
    "value": "YOUR_MESSAGE",
    "apiid": "YOUR_SESSION_ID"
}

Tips for StreamDeck Setup

Use URL encoding for special characters in messages
You can create multiple buttons for different preset messages
Chain commands using Multi Actions for complex sequences
Add a delay between actions if needed using StreamDeck's delay feature

Testing Your Setup

Find your session ID from the Social Stream API Sandbox
Create a test button with a simple message
Press the button to verify the message appears in your social platforms
Check the Social Stream API Sandbox's incoming messages panel to confirm delivery

Channel-Specific Messages

To send to specific channels, add the channel parameter:

https://io.socialstream.ninja/YOUR_SESSION_ID/sendChat/null/YOUR_MESSAGE?channel=2

Channels:

1: General communication
2: Dock
3: Featured content
4-7: Custom channels

Using Bitfocus Companion with Social Stream Ninja

Bitfocus Companion enables the reasonably priced Elgato Streamdeck to be a professional shotbox surface for a huge amount of different presentation switchers, video playback software and broadcast equipment. It supports Social Stream Ninja and VDO.Ninja!

https://bitfocus.io/companion https://bitfocus.io/connections/socialstream-ninja

Initial Setup

Enable API Control:
- Open Social Stream Ninja
- Go to Global settings and tools > Mechanics
- Enable Enable remote API control of extension
Get Your Session ID:
- Navigate to Global settings and tools > Session Options
- Copy your Session ID
- Alternatively, find it in your URL after ?session=
Configure Companion:
- Install the Social Stream Ninja module in Companion
- Paste your Session ID into the module settings

Available Actions

The following commands are confirmed available in Companion:

Clear featured message
Clear all messages
Next in queue
Toggle auto-show
Feature next un-featured
Reset Poll
Close Poll
Waitlist Controls
Text to Speech (TTS) Controls
Send Chat Message

Variables

Companion can access:

queue_size: Shows the current queue size

Comparison with StreamDeck

Advantages of using Companion:

Native integration with Social Stream Ninja
No need for URL encoding or complex HTTP requests
Direct access to all core functionality
Real-time queue size monitoring through variables
Can be used alongside StreamDeck for more complex setups

This makes Companion a simpler alternative to the StreamDeck HTTP method described above, especially for basic Social Stream Ninja control.

Uh oh!

FilesExpand file tree

api.md

Latest commit

History

api.md

File metadata and controls

Social Stream Ninja API Documentation

WebSocket API

Choose Your Use Case

Quick Start: Remote Control (StreamDeck / Bitfocus Companion)

Quick Start: Receiving Chat Messages (Python / Node.js)

Connecting to the API Server

Channel System Explained

Available Commands

Channel-Specific Messaging

HTTP API

Channel Parameter

Server-Sent Events (SSE)

Receiving Responses

Response Types

Special Pages and Features

Message Targeting System

How it works

Use Cases

Best Practices

Inbound Donation Webhooks

Prerequisites

Supported Platforms

Stripe Setup

Ko-Fi Setup

Buy Me A Coffee Setup

Fourthwall Setup

Security Note

Donation Message Format

Featured Page (featured.html)

Connection Options

Content Filtering Options

API Actions

Content Object Structure

Additional Features

Best Practices and Improvements

Example API Usage

Dock Page (dock.html)

Connection Options

URL Parameters

WebSocket Message Processing

Key Features

API Actions

Example API Usage

Best Practices and Improvements

Social Stream Ninja API Documentation

Extension

WebSocket Connections

Message Flow

API Actions

Example API Usage

Best Practices and Improvements

Integration with Other Components

Waitlist Page (waitlist.html)

WebSocket Connection

Key Functions

Waitlist Display Modes

Message Types and Actions

Key Features

CSS Classes for Styling

API Actions

Best Practices and Improvements

Integration with Other Components

Battle royale, Polls, etc

Poll Control via API

Basic Poll Controls

Advanced Poll Controls

Example Usage

Timer Control via API

Basic Timer Controls

Setting Timer State

Example Usage

Battle Page (battle.html)

Communication Method