Sessions, Passwords, and Relay Modes

One matching session connects sources, docks, overlays, alerts, and API pages. Routing flags must match too.

The Connection Model

  1. A source captures chat or an event and publishes it to a Social Stream session.
  2. The Dock, Featured overlay, Multi Alerts, Event Flow, and other pages join that same session.
  3. If a password is set, every joining page must use the same password.
  4. If server routing is enabled, the active pages must use the newly generated URLs with the matching routing parameters.
Source → same session ID + password + routing mode → Dock / overlay / API consumer

Session ID And Password

Open Global settings and tools → Session Options to view the current session ID and set an optional password.

Social Stream Ninja Session Options showing the session ID field, optional password field, and Hide your links control
Use a placeholder in documentation and screenshots. Never publish a real session password or a private generated link.
ValueRule
Session IDKeep it unchanged unless you intend to replace every source, dock, overlay, and integration URL that uses it.
PasswordOptional, but must match everywhere once set. Copy newly generated links after adding or changing it.
Generated linkTreat the whole link as private when it includes a password or other sensitive parameters.

Prefer copying generated URLs. They already include the current session, password, page version, and supported routing options. Hand-edited links are a common source of blank pages.

Default, Relay, And API Server Modes

ControlWhat It ChangesWhen To Use It
Default links Normal Social Stream peer/session transport, with no server flag added. Most single-computer and normal OBS setups.
Enable remote API control of extension Enables extension HTTP/WebSocket control and inbound webhook handling. External apps, Stream Deck/API control, or supported inbound donation webhooks.
Enable Dock to use and publish via API server Adds the page's server routing where supported. The Dock/Featured workflow needs remote API-server control instead of its normal path.
Send chat messages to API server Routes captured chat to the API-server listener path and adds server2 to supported generated links. Python, Node, or another external WebSocket listener must receive chat.
Also send API-routed chat normally Temporary additive delivery through both paths. Only during a deliberate mixed-mode transition; it can duplicate messages.
Dock commands via server Adds server3 where supported so Dock commands return through the server path. Peer connections are blocked or unreliable and Dock-to-extension commands need the server.
Social Stream Ninja global Mechanics controls for remote API control, Dock API-server publishing, external chat listeners, additive delivery, and Dock commands via server
The current routing controls. Changing the three Dock/API transport toggles updates generated links; it does not rewrite an already open page or a saved OBS Browser Source.

About localserver

Some pages accept localserver and use a local WebSocket endpoint at ws://127.0.0.1:3000. Add localserverport=PORT to select another port between 1024 and 65535. Invalid or omitted values safely fall back to port 3000. Note that new installs of the Social Stream desktop app run their local server on port 3003 instead, and stamp localserverport=3003 into the links they generate — so if you hand-write a URL against a new install, add that parameter yourself. Add these parameters only when that local server is actually running and the exact page supports them.

Routing parameters are page-specific. server, server2, server3, localserver, and localserverport do not have one universal behavior on every overlay. Use the generated URL for the exact page rather than copying flags from a different tool.

After Changing A Session Or Routing Toggle

  1. Copy the newly generated Dock or overlay URL.
  2. Close and reopen active browser pages that use the old URL.
  3. Replace the URL in saved OBS Browser Sources and refresh their cache.
  4. Reload or reactivate source pages if the session ID or password changed.
  5. Send one fake test message and confirm it reaches the Dock before testing the final overlay.

Blank Dock Or Overlay Checklist

  1. Compare the complete session= value on the source, Dock, and overlay.
  2. Check whether one URL is missing the current password=.
  3. Check whether an old OBS URL lacks the current server routing flags.
  4. Remove manually added routing flags and copy a fresh generated URL if the modes are unclear.
  5. Test the Dock first. If the Dock receives messages, troubleshoot the overlay's event filters and URL options next.
  6. See OBS Troubleshooting and the Commands & API reference for deeper checks.