SocialStream.Ninja Integration with Streamer.bot

Integration Features

• Centralized Processing: Receive messages from various platforms supported by SocialStream.Ninja and process them within Streamer.bot.
• Custom Actions: Trigger any Streamer.bot action based on incoming messages (play sounds, show alerts, send messages to Twitch/YouTube, control OBS, etc.).
• Filtering/Routing: Use Streamer.bot's logic (C#, If/Else sub-actions) to handle messages differently based on platform, user, or content.
• Reliable Connection: Uses WebSockets for a persistent, low-latency connection.

Prerequisites

• Streamer.bot installed on your computer (v0.2.0 or higher recommended)
• SocialStream.Ninja's Standalone app installed and configured
• Basic familiarity with Streamer.bot's interface (Actions, Sub-Actions)

Setting Up Streamer.bot WebSocket Server

1. In Streamer.bot, go to Servers/Clients → WebSocket Server
2. Enable the server by checking Enabled
3. Check Auto Start to start the server automatically when Streamer.bot launches
4. Note the Port (default is 8080)
5. Optionally enable Authentication and set a password if required. If you set a password here, you *must* enter it in SocialStream.Ninja settings.
6. Click Start if the server isn't running. The status should show "Listening".
7. Click Apply or Save (depending on SB version)

Setting Up the Streamer.bot Action (Required)

To process messages from SocialStream.Ninja, you must create an Action in Streamer.bot. SocialStream.Ninja will trigger this action for each incoming message.

1. In Streamer.bot, navigate to the Actions tab
2. Right-click in the actions pane and select Add
3. Name your action clearly (e.g., "Process SocialStream Message")
4. Very Important: After creating the action, right-click on it and select Copy Action ID. You will paste this ID into the SocialStream.Ninja settings.
5. Add sub-actions to handle the message data. A common first step is to extract the data using C#. Right-click the action → Add Sub-Action → Core → C# → Execute C# Code
6. Paste the following C# code. This code extracts the chat data sent by SocialStream.Ninja from the `chatData` argument:

using System;
using Newtonsoft.Json.Linq; // Make sure Newtonsoft.Json is referenced
public class CPHInline
{
    public bool Execute()
    {
        // --- Get the main chatData object sent from SocialStream.Ninja ---
        JObject chatData = null;
        if (args.ContainsKey("chatData") && args["chatData"] is JObject)
        {
            chatData = (JObject)args["chatData"];
        }
        else
        {
             CPH.LogWarn("[SocialStream] Action triggered but 'chatData' argument was missing or not a JSON object.");
             // Try converting if it's a string representation of JSON (less ideal)
             if (args.ContainsKey("chatData") && args["chatData"] is string) {
                try {
                    chatData = JObject.Parse((string)args["chatData"]);
                } catch (Exception ex) {
                    CPH.LogError($"[SocialStream] Failed to parse chatData string: {ex.Message}");
                    return false;
                }
             } else {
                 return false; // Exit if we definitely don't have chatData
             }
        }
        // --- Extract specific fields from the chatData object ---
        string message = GetStringValue(chatData, "chatmessage", ""); 
        string username = GetStringValue(chatData, "chatname", "Unknown User");
        string userId = GetStringValue(chatData, "userid", "");
        string avatar = GetStringValue(chatData, "chatimg", "");
        bool isBot = GetBoolValue(chatData, "isBot", false);
        string originalPlatform = GetStringValue(chatData, "originalPlatform", "unknown");
        string source = GetStringValue(chatData, "source", "unknown");
        
        // Log the received message to Streamer.bot's Action Queue logs for debugging
        CPH.LogInfo($"[SocialStream][{originalPlatform}] {username}: {message}");
        
        // --- Set arguments for subsequent sub-actions ---
        CPH.SetArgument("ss_message", message);
        CPH.SetArgument("ss_username", username);
        CPH.SetArgument("ss_userId", userId);
        CPH.SetArgument("ss_avatar", avatar);
        CPH.SetArgument("ss_isBot", isBot);
        CPH.SetArgument("ss_platform", originalPlatform);
        CPH.SetArgument("ss_source", source);
        
        return true;
    }
    
    // Helper methods to safely get values from JObject with specific types
    private string GetStringValue(JObject obj, string key, string defaultValue)
    {
        try
        {
            if (obj != null && obj.TryGetValue(key, StringComparison.OrdinalIgnoreCase, out JToken token))
            {
                return token.ToString();
            }
        }
        catch (Exception ex) {
             CPH.LogWarn($"[SocialStream] Error getting value for key '{key}': {ex.Message}");
        }
        return defaultValue;
    }
    
    private bool GetBoolValue(JObject obj, string key, bool defaultValue)
    {
        try
        {
            if (obj != null && obj.TryGetValue(key, StringComparison.OrdinalIgnoreCase, out JToken token))
            {
                return token.ToObject<bool>();
            }
        }
        catch (Exception ex) {
             CPH.LogWarn($"[SocialStream] Error getting value for key '{key}': {ex.Message}");
        }
        return defaultValue;
    }
}

6. Click Compile. If it shows "Compiled successfully!", click OK.
7. Add more sub-actions *after* the C# code sub-action to use the data (e.g., send messages, play sounds). Use the arguments set in the C# code (like `%ss_message%`, `%ss_username%`, `%ss_platform%`). For example:
   • Right-click → Add Sub-Action → Twitch → Chat → Send Message
   • Set Message to: `[%ss_platform%] %ss_username%: %ss_message%`
   • Check "Use Arguments" (or ensure variables are enabled)
8. Click Save to save the entire action.

Configuring SocialStream.Ninja

1. In SocialStream.Ninja's menu, go to Global settings and tools → Mechanics (or similar path).
2. Find the Streamer.bot integration section.
3. Toggle the integration **ON**.
4. Set the **WebSocket URL** to match Streamer.bot (e.g., `ws://127.0.0.1:8080`). Use `127.0.0.1` if SSN is on the same PC as Streamer.bot.
5. If you set a password in Streamer.bot's WebSocket Server settings, enter it in the **Password** field here.
6. **Action ID (Required):** Paste the Action ID you copied from Streamer.bot into this field. This is required for the integration to function.
7. Save your settings in SocialStream.Ninja.

SocialStream.Ninja Data Structure Reference

When SocialStream.Ninja sends data to Streamer.bot, it passes a detailed JSON object with the following fields that you can access in your Streamer.bot actions. The example C# code above extracts these fields and makes them available as arguments.

Accessing Additional Fields in C#

To access fields not already extracted in the example C# code, add lines like:

// Extract additional fields as needed
string contentImage = GetValue<string>(chatData, "contentimg", "");
string subtitle = GetValue<string>(chatData, "subtitle", "");
string nameColor = GetValue<string>(chatData, "nameColor", "#FFFFFF");

// Make them available as arguments
CPH.SetArgument("ss_contentImage", contentImage);
CPH.SetArgument("ss_subtitle", subtitle);
CPH.SetArgument("ss_nameColor", nameColor);

Example: Working with Platform-Specific Messages

You can add conditional logic based on the platform or other message properties:

// Example: Process messages differently based on platform
if (originalPlatform.Equals("youtube", StringComparison.OrdinalIgnoreCase))
{
    // YouTube-specific processing
    CPH.PlaySound("sounds/youtube_alert.mp3");
    
    // Check for YouTube memberships
    string membership = GetValue<string>(chatData, "membership", "");
    if (!string.IsNullOrEmpty(membership))
    {
        CPH.SetArgument("ss_hasMembership", true);
        CPH.SetArgument("ss_membershipInfo", membership);
        CPH.LogInfo($"[YouTube Membership] {username}: {membership}");
    }
}
else if (originalPlatform.Equals("twitch", StringComparison.OrdinalIgnoreCase))
{
    // Twitch-specific processing
    string badges = GetValue<string>(chatData, "chatbadges", "");
    bool isSubscriber = badges.Contains("subscriber");
    CPH.SetArgument("ss_isSubscriber", isSubscriber);
}

Example: Creating Custom Text Formats

You can format messages for display in various ways:

// Standard format with platform
string formattedMessage = $"[{originalPlatform.ToUpper()}] {username}: {message}";
CPH.SetArgument("ss_formattedMessage", formattedMessage);

// HTML format for web display
string htmlFormat = $"<span style='color:{GetValue<string>(chatData, "nameColor", "#FFFFFF")}'>{username}</span>: {message}";
CPH.SetArgument("ss_htmlMessage", htmlFormat);

// Format for OBS Text Source
string obsText = $"{originalPlatform} | {username} says: {message}";
CPH.SetArgument("ss_obsText", obsText);

Troubleshooting

• Cannot connect to WebSocket:
  • Verify the WebSocket Server is **Enabled** and **Running** (Status: Listening) in Streamer.bot (Servers/Clients → WebSocket Server).
  • Ensure the **Port** in SocialStream.Ninja matches the Port in Streamer.bot.
  • Check firewall rules on your PC aren't blocking the connection (especially if not using `127.0.0.1`).
  • Verify the **Password** matches exactly if authentication is enabled in Streamer.bot (or that it's blank in both if disabled).
  • Check the SocialStream.Ninja console logs (usually F12 in the app/browser) for connection errors.
• Messages not triggering Action in Streamer.bot:
  • Verify the **Action ID** in SocialStream.Ninja settings exactly matches the ID copied from Streamer.bot (right-click action -> Copy Action ID).
  • Check the Streamer.bot **Action Queues** tab (under Processing) to see if the action is being triggered but failing. Look for errors.
  • Ensure the C# code in your action compiles successfully.
  • Add a simple `Core -> Misc -> Log Message` sub-action as the *first* sub-action in your Streamer.bot action to confirm it's being triggered at all.
  • Check the SocialStream.Ninja console logs for errors when sending the `DoAction` request.
• Arguments not working in Sub-Actions:
  • Ensure the C# sub-action runs *before* the sub-actions that use the arguments.
  • Double-check the argument names set in C# (`CPH.SetArgument("ss_message", ...)` correspond to the variables used in sub-actions (`%ss_message%`).
  • Ensure the "Use Arguments" option (or similar) is enabled in the sub-actions that need them.

Important Note on Direct Chat Display