docs: Clarify API toggles and channels for remote control vs chat listener use cases

- Updated popup.html toggle descriptions with clearer tooltips explaining each toggle's purpose
- Added emoji indicator (📡) to "Send chat messages to API server" toggle to highlight its importance
- Added "Quick Start" section to api.md with two clear use cases:
  - Remote Control (StreamDeck/Bitfocus): Toggle 1, Channel 1
  - Chat Listener (Python/Node): Toggle 1+3, Channel 4
- Added Python and Node.js sample code for receiving chat messages
- Updated sampleapi.html with clear use case guidance
- Updated docs/commands.html with toggle requirements and improved channel descriptions
- Updated docs/customoverlays.md WebSocket section with toggle reference table

Fixes confusion where users enable API control but don't receive chat messages
because they missed enabling the 3rd toggle for chat relay to channel 4.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: steveseguin

api.md

@@ -88,6 +88,126 @@ The WebSocket API allows real-time, bidirectional communication between your app
 
 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](https://github.com/steveseguin/ninjasdk/blob/main/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/sendEncodedChat/null/Hello%20World
+```
+
+**WebSocket commands:**
+```javascript
+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: "sendChat", value: "Hello from API!" }));
+};
+```
+
+See the [StreamDeck Integration Guide](#streamdeck-integration-guide-for-social-stream-ninja) and [Bitfocus Companion](#using-bitfocus-companion-with-social-stream-ninja) 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):**
+1. ✅ **Enable remote API control of extension**
+2. ✅ **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:**
+
+```python
+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:**
+
+```javascript
+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`.

docs/commands.html

@@ -206,7 +206,12 @@ <h4>Message Export</h4>
 				</div>
 
 				<div class="command-note">
-					<p><strong>Important:</strong> You must enable the Server API toggle in the extension menu for API functionality to work.</p>
+					<p><strong>Required Settings (Global settings → Mechanics):</strong></p>
+					<ul style="text-align:left; margin: 10px 0;">
+						<li><strong>🎮 Remote Control (StreamDeck/Bitfocus):</strong> Enable <em>"Enable remote API control of extension"</em> (Toggle 1) — Connect to <strong>channel 1</strong></li>
+						<li><strong>📡 Chat Listener (Python/Node apps):</strong> Enable Toggle 1 + <em>"Send chat messages to API server"</em> (Toggle 3) — Connect to <strong>channel 4</strong></li>
+					</ul>
+					<p>See the <a href="../api.md">full API documentation</a> for detailed setup guides and code samples.</p>
 				</div>
 
 			<div class="command-card">
@@ -241,19 +246,23 @@ <h4><i class="fas fa-broadcast-tower"></i> Server-Sent Events</h4>
 
 				<div class="channel-system">
 					<h4>Channel System</h4>
-					<p>The API uses a channel system for message routing control:</p>
+					<p>The API uses a channel system for message routing:</p>
 					<div class="code-block">
 						<pre>
-	- 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 1: Remote control commands (default for StreamDeck/Bitfocus)
+	- Channel 2: Dock page output
+	- Channel 3: Extension receives commands from Dock
+	- Channel 4: <strong>Chat messages from Extension</strong> (use this to receive Twitch/YouTube chat!)
+	- Channel 5: Waitlist/giveaway communication
 	- Channels 6-9: Reserved for future use</pre>
 					</div>
-					<p>You can specify input and output channels when connecting:</p>
+					<p>Connect with your desired channel:</p>
 					<div class="code-block">
-						<pre>wss://io.socialstream.ninja/join/SESSION_ID/IN_CHANNEL/OUT_CHANNEL</pre>
+						<pre>// 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</pre>
 					</div>
 				</div>
 			</div>

docs/customoverlays.md

@@ -91,15 +91,21 @@ See `dock.html`, `featured.html`, `events.html` etc. for more examples of iframe
 
 For more direct control or server-side integrations, you can connect to the SSN WebSocket server (`wss://io.socialstream.ninja`). This bypasses the need for an iframe but requires handling the WebSocket connection and message parsing directly in your JavaScript.
 
+**Required Settings (Global settings → Mechanics):**
+
+| Use Case | Required Toggles | Channel |
+|----------|-----------------|---------|
+| **Remote Control** (send commands) | Toggle 1: "Enable remote API control of extension" | Channel 1 (default) |
+| **Chat Listener** (receive chat messages) | Toggle 1 + Toggle 3: "Send chat messages to API server" | Channel 4 |
+
 **Connection:**
 
 ```javascript
 const urlParams = new URLSearchParams(window.location.search);
 const roomID = urlParams.get("session") || "test";
-// Choose appropriate IN_CHANNEL and OUT_CHANNEL based on your needs.
-// For a simple overlay listening to general messages, IN_CHANNEL 3 or 4 might be suitable.
-const inChannel = urlParams.get("in_channel") || "4"; // Channel to listen on
-const outChannel = urlParams.get("out_channel") || "3"; // Channel to send to (if needed)
+// Channel 4 receives chat messages when "Send chat messages to API server" toggle is enabled
+const inChannel = urlParams.get("in_channel") || "4"; // Channel 4 = chat messages from extension
+const outChannel = urlParams.get("out_channel") || "3"; // Channel to send commands (if needed)
 
 const socketServerURL = urlParams.get("server") || "wss://io.socialstream.ninja";
 const socket = new WebSocket(socketServerURL);
@@ -181,13 +187,13 @@ A typical message object might look like this (fields vary based on source and e
 }
 ```
 
-Refer to `about.md` for more details on these fields.
-
-> **Note:** Reserve the `event` field for true system notifications (follows, raids, /me actions, etc.). Regular chat messages should leave `event` unset/false so they are never mistaken for events.
-
-### Client-Side Filtering and Logic
-
-Your JavaScript code will be responsible for deciding what to do with each incoming message.
+Refer to `about.md` for more details on these fields.
+
+> **Note:** Reserve the `event` field for true system notifications (follows, raids, /me actions, etc.). Regular chat messages should leave `event` unset/false so they are never mistaken for events.
+
+### Client-Side Filtering and Logic
+
+Your JavaScript code will be responsible for deciding what to do with each incoming message.
 
 ```javascript
 function processIncomingSSNMessage(data) {
@@ -591,4 +597,4 @@ This example shows an overlay that only displays new follower and subscriber eve
   - **No `background.js` Modification:** Design your custom page to work with the existing SSN message structure and API. Avoid solutions that would require changing the core extension code.
   - **Consult Examples:** The existing `dock.html`, `featured.html`, `events.html`, `hype.html`, `waitlist.html`, `confetti.html`, and `credits.html` files in the Social Stream Ninja project are excellent resources for seeing how these principles are applied.
 
-By following this guide, you can create powerful and customized overlay experiences for Social Stream Ninja.
+By following this guide, you can create powerful and customized overlay experiences for Social Stream Ninja.

manifest.json

@@ -2,7 +2,7 @@
   "name": "Social Stream Ninja",
   "description": "Powerful tooling to engage live chat on Youtube, Twitch, Zoom, and more.",
   "manifest_version": 3,
-  "version": "3.39.3",
+  "version": "3.39.4",
   "homepage_url": "http://socialstream.ninja/",
   "browser_specific_settings": {
     "gecko": {

popup.html

@@ -5439,7 +5439,7 @@ <h3>Printer Control</h3>
                                     </label>
                                     <span data-translate="disable-host-chat">🚫🗨️ Disable the host chat and block functions </span>
                                 </div>
-								 <div title="See documentation on socialstream.ninja for details.">
+								 <div title="Allows external apps (Python, Node, StreamDeck, etc.) to control SSN via HTTP/WebSocket API. Enable this to send commands like sendChat, blockUser, etc. to the extension.">
                                     <label class="switch">
                                         <input type="checkbox" data-setting="socketserver" />
                                         <span class="slider round"></span>
@@ -5449,21 +5449,21 @@ <h3>Printer Control</h3>
                                         <span data-translate="remote-httpwss-api-control-extension">remote API control of extension</span>
                                     </a>
                                 </div>
-                                <div title="This is needed if HTTP/WSS commands are being sent to the dock for remote control, to bypass p2p if needed, and to publish featured messages via server instead of P2P">
+                                <div title="Connects the Dock/Featured pages to the API server for remote control. Needed if you want to send commands (clear, feature, nextInQueue, etc.) directly to the Dock via HTTP/WebSocket.">
                                     <label class="switch">
                                         <input type="checkbox" id="server" data-both="server" />
                                         <span class="slider round"></span>
                                     </label>
                                     <span data-translate="send-featured-chat-via-server-instead-of-p2p">Enable Dock to use and publish via API server</span>
                                 </div>
-                                <div  title="Mainly useful if P2P not working. It can also be used to send messages to the Dock via the API using channel 3/4">
+                                <div  title="IMPORTANT: Enable this to receive chat messages via WebSocket API! Routes chat from Twitch/YouTube/etc. through the API server (channel 4) so external apps can listen. Required for Python/Node chat listeners.">
                                     <label class="switch">
                                         <input type="checkbox" id="server2" data-both="server2" />
                                         <span class="slider round"></span>
                                     </label>
-                                    <span data-translate="send-messages-to-dock-via-server-instead-of-p2p">Send messages to Dock from Extension via server</span>
+                                    <span data-translate="send-messages-to-dock-via-server-instead-of-p2p">📡 Send chat messages to API server (for external listeners)</span>
                                 </div>
-                                <div title="Mainly useful if P2P not working in cases where you want to send messages to a social end point via the Dock page.">
+                                <div title="Allows the Dock page to send commands back to the extension via the API server instead of P2P. Useful if P2P connections are blocked or unreliable.">
                                     <label class="switch" >
                                         <input type="checkbox" id="server3" data-both="server3" />
                                         <span class="slider round"></span>

sampleapi.html

@@ -197,7 +197,12 @@ <h1 class="mb-4">Social Stream API Sandbox</h1>
 			<p class="lead">
 				This Social Stream API Sandbox is a comprehensive tool for developers to test and interact with the Social Stream Ninja API. It provides a user-friendly interface to experiment with various API features, including message generation, user management, and channel-specific communications. For full API documentation, please visit <a href="https://socialstream.ninja/api" target="_blank">socialstream.ninja/api</a>.
 				<br/><br/>
-				Please note that you may need to add <b><i>&server</i></b> to the dock.html or featured.html pages if you wish to send messages to them via the API. By default the extension, nor any dock/overlay page, will connect to the API server by default; they must be configured to work with the API server via menu toggle or URL parameter.
+				<b>🎮 Remote Control (StreamDeck/Bitfocus):</b> Send commands like clear, nextInQueue, sendChat<br/>
+				→ Enable: <b>Toggle 1</b> (Enable remote API control) — Connect to <b>channel 1</b> (default)<br/><br/>
+				<b>📡 Chat Listener (Python/Node apps):</b> Receive chat messages from Twitch/YouTube/etc.<br/>
+				→ Enable: <b>Toggle 1 + Toggle 3</b> (Send chat messages to API server) — Connect to <b>channel 4</b><br/><br/>
+				<b>Settings Location:</b> Global settings &gt; Mechanics<br/>
+				<small>Alternatively, add <b>&server</b> or <b>&server2</b> URL parameters to dock.html/featured.html pages.</small>
 			</p>
 		</div>
 
@@ -379,24 +384,24 @@ <h2>Channel-Specific Messaging</h2>
                     <option value="7">Channel 7</option>
                 </select>
             </div>
-            <button class="btn btn-primary" onclick="sendChannelMessage()">Send Channel Message</button>
-            <p class="note">Send messages to specific channels of the API server for more granular control of API messaging.</p>
-        </div>
-
-        <div class="section">
-            <h2>Message Filters</h2>
-            <div class="btn-group" role="group">
-                <button class="btn btn-info" onclick="sendCommand('emoteonly', 'toggle')">Toggle Emote-only</button>
-                <button class="btn btn-success" onclick="sendCommand('emoteonly', true)">Enable Emote-only</button>
-                <button class="btn btn-danger" onclick="sendCommand('emoteonly', false)">Disable Emote-only</button>
-            </div>
-            <p class="note">Emote-only mode keeps only emotes/emoji from chat messages and drops messages that become empty after filtering.</p>
-        </div>
-		
-        <div class="section">
-            <h2>Waitlist Commands</h2>
-            <div class="btn-group" role="group">
-                <button class="btn btn-warning" onclick="sendCommand('removefromwaitlist', 1)">Remove First from Waitlist</button>
+            <button class="btn btn-primary" onclick="sendChannelMessage()">Send Channel Message</button>
+            <p class="note">Send messages to specific channels of the API server for more granular control of API messaging.</p>
+        </div>
+
+        <div class="section">
+            <h2>Message Filters</h2>
+            <div class="btn-group" role="group">
+                <button class="btn btn-info" onclick="sendCommand('emoteonly', 'toggle')">Toggle Emote-only</button>
+                <button class="btn btn-success" onclick="sendCommand('emoteonly', true)">Enable Emote-only</button>
+                <button class="btn btn-danger" onclick="sendCommand('emoteonly', false)">Disable Emote-only</button>
+            </div>
+            <p class="note">Emote-only mode keeps only emotes/emoji from chat messages and drops messages that become empty after filtering.</p>
+        </div>
+		
+        <div class="section">
+            <h2>Waitlist Commands</h2>
+            <div class="btn-group" role="group">
+                <button class="btn btn-warning" onclick="sendCommand('removefromwaitlist', 1)">Remove First from Waitlist</button>
                 <button class="btn btn-warning" onclick="sendCommand('highlightwaitlist', 1)">Highlight First in Waitlist</button>
                 <button class="btn btn-warning" onclick="sendCommand('resetwaitlist')">Reset Waitlist</button>
                 <button class="btn btn-warning" onclick="sendCommand('downloadwaitlist')">Download Waitlist</button>
@@ -936,4 +941,4 @@ <h2>Incoming Messages</h2>
 		});
 		</script>
 		</body>
-		</html>
+		</html>