Event Flow Editor Guide

0. Quick Orientation

What is this editor?

The Event Flow editor is the “advanced automation” layer for Social Stream Ninja. It sits above the simple popup switches and lets you script your own routing logic. Use it when you need to:

• Relay chat between services with filters (e.g., mirror Twitch to Discord but block commands).
• Build loyalty-based commands, keyword games, or raffle gating with AND/OR/NOT logic.
• Trigger custom overlays, audio, OBS scenes, or webhooks based on data you enrich in the flow.
• Mix multiple platforms inside a single automation (Kick + Twitch + YouTube routed through one flow).

Think of the popup as “quick presets” and Event Flow as the toolkit for bespoke workflows.

Flow Actions Overlay (Action Output)

Nodes such as Play Audio Clip, Display Media Overlay, and the OBS controls need a rendering surface. That surface is the Flow Actions overlay page served from actions.html. Keep it running in your broadcasting software (OBS/Streamer.bot browser docks/etc.) so Event Flow actions have somewhere to appear.

Once loaded, that overlay can:

• Show Tenor/GIPHY media, text, and confetti triggered by your flows.
• Play sounds (TTS, audio clips) locally so viewers hear them.
• Talk to OBS via the WebSocket settings that live under the Flow Actions section in the popup (scene switching, source toggles, replay buffer, etc.).

1. What Moves Through a Node?

The Event Flow runtime passes two things through every wire:

1. Payload – the event or message data object.
2. Gate signal – a true/false bit telling the next node whether to run.

Input Expectations

• Event Sources (Twitch Message, Timers, Manual Trigger, etc.) ignore upstream input—they generate their own payload and always emit true unless the node itself errors.
• Transform & Logic Nodes read the payload and may rewrite fields, set state, or flip the gate signal to false.
• Action Nodes fire only when the gate remains true. They can still output an updated payload if you want to keep chaining actions.

Output Patterns

2. Logic Node Cheatsheet

These blocks answer the most common "What does true/false mean?" questions.

3. Example Micro-Flows

A. Auto-reply Unless the Message Is a Command

Here the Regex node emits true when the line is a command. We route the false socket to our reply, so regular chatters get an acknowledgement while commands simply pass through.

B. Require Multiple Checks with AND

The AND node ensures only members using the right keyword relay to Discord. Both branches send their boolean result to the AND node; the payload from the first branch continues downstream.

C. NOT Node to Block Repeat Alerts

State Check outputs true when the alert is muted. By inverting that result, the NOT node makes sure we only play the celebration when the flag is false.

4. Preventing Echoes, Loops, and Relay Feedback

Relaying chat between surfaces is powerful but can echo infinitely if you listen to your own output. Follow these safeguards:

• Tag relayed messages. Set meta.source = "relay" before sending, then add a "Skip if meta.source = relay" gate near your entry nodes.
• Use Debounce or Cooldown nodes for alerts that should only fire once every X seconds.
• Break cycles intentionally. If two branches feed each other, add a logic node that checks a state variable ("currentlyRelaying") so the flow exits early when the flag is set.

5. Inputs, Outputs, and Practical Questions

Common Q & A

• Do I have to use AND for every pair of filters? No. Many nodes include multiple checks (for example, the basic Message Filter supports keyword + role). Use AND only for advanced combinations or when merging signals from different nodes.
• How do true/false values reach the NOT node? Any node with a green output emits true by default. When a condition fails, it emits false. Connect that wire into NOT to invert the result.
• Can a node emit a payload even if it returns false? Yes. The payload still travels through the false output; it is up to you to decide where that branch should go.

6. Template Variables Reference

Several action nodes (Show Text, Send Message, Relay Chat, TTS Speak) support template variables that get replaced with event data at runtime. Wrap variable names in curly braces like {username}.

Core Variables (backward compatible)

Extended Variables

Example Templates

• Show Text: {username} just cheered {hasDonation}!
• Relay Chat: [{source}] {username}: {message}
• TTS: {username} says {message}
• Donation Alert: {username} donated {donation} - {subtitle}

7. Best Practices Checklist

• Name & color your nodes so future-you knows which branch is which.
• Test with the built-in simulator (Send Test Event) before pushing a flow live.
• Group logic near the source. Filter as early as possible to avoid extra processing down the line.
• Store repeats in State nodes. Use counters, toggles, and timestamps to avoid double alerts.
• Document meta fields. When you add custom meta keys, note them so overlays and remote clients stay consistent.

8. Further Exploration

Ready for more depth?

• Use State Nodes (counters, toggles, timers) to track context between events.
• Combine Variables + Logic to build queue systems, raffles, or scoring engines.
• Hook into the Points & Rewards system so viewers can intentionally trigger flows.
• Running the SSApp desktop app? Unlock Custom JavaScript nodes for arbitrary logic that no built-in node covers.
• Check the Event Reference for detailed payload documentation across all platforms.

This guide is intentionally standalone—copy it locally, adapt it for your team, and keep experimenting inside the editor.

9. Custom JavaScript SSApp / Desktop only

Two nodes in the Event Flow editor let you write arbitrary JavaScript that runs inside the flow pipeline: Custom Code (trigger) and Execute Custom Code (action). They are the escape hatch for anything the built-in nodes cannot express.

Custom Code — Trigger node

Drag Custom Code from the Advanced group in the Triggers panel onto the canvas. It acts as a gate: the flow continues only when your code returns true.

Execute Custom Code — Action node

Drag Execute Custom Code from the Integrations group in the Actions panel. It can mutate the message, block it, or attach metadata that downstream nodes can read.

The message object

Both nodes receive the full event payload as message. The fields below are always available; platform-specific events may include additional ones.

What the action returns

Return a plain object from your action code. Any fields you include are merged into the flow's result object; fields you omit keep their current values.

Snippet examples

Copy any of these into the JavaScript Code textarea of the matching node type.

Trigger snippets — return true to continue the flow

Action snippets — return { modified, message }

Complete example — VIP feature request bot

This flow listens for !feature <text> from subscribers, VIPs, or mods, reformats it as a feature request, and relays it to a second destination (e.g. Discord).

Step 1 — Custom Code trigger (paste into the trigger's JavaScript Code field):

Step 2 — Execute Custom Code action (paste into the action's JavaScript Code field):

Step 3 — Relay Chat action: add a standard Relay Chat node after the action and configure it to point at your Discord (or other) destination. No custom code needed here — the reformatted message.chatmessage flows through automatically.

Security considerations

• No network sandbox. Action code can call fetch(). If you're accepting shared flows from others, audit the JS before activating them.
• Errors are caught. A runtime error in your code returns false (trigger) or a no-op (action) and logs to the DevTools console — the flow doesn't crash.
• Syntax errors too. A SyntaxError at compile time is caught the same way. Check DevTools (F12) if a node appears to do nothing.