WebSocket Protocol (Custom Integrations)

Overview

In addition to the built-in platform connections (TikTok, Twitch, YouTube, Kick, Streamlabs, StreamElements), VMSC exposes a Custom WebSocket Server that external applications can connect to, and supports Custom WebSocket Client connections to receive events from arbitrary sources. This enables integration with bots, game engines, home automation, and any other software that speaks WebSocket.

Built-in Connections Overview

For reference, here is how VMSC connects to each built-in platform. The custom WebSocket protocol described on this page is separate from all of these.

Custom WebSocket Server

VMSC runs a WebSocket server that external applications can connect to. This allows you to send events into VMSC (e.g., from a game, a chatbot, or a hardware controller) and receive events from VMSC (e.g., to display data in a custom application).

Configuration

Authentication

Clients must include the auth token when connecting. Pass it as a query parameter or in the Authorization header:

// Query parameter
ws://localhost:7895?token=YOUR_AUTH_TOKEN

// Or Authorization header
Authorization: Bearer YOUR_AUTH_TOKEN

Connections without a valid token are rejected with a 4401 close code.

Message Format

All messages sent to and from the VMSC custom WebSocket use JSON. Every message has an action field that determines the message type.

Injecting Events (Client → VMSC)

Send an event into the VMSC rule engine as if it came from a connected platform.

{
  "action": "injectEvent",
  "event": {
    "type": "chat",
    "source": "custom",
    "user": {
      "id": "user-123",
      "username": "MyBot",
      "nickname": "My Bot"
    },
    "data": {
      "message": "Hello from my custom app!"
    }
  }
}

VMSC responds with an acknowledgment:

{
  "action": "injectEvent",
  "status": "ok",
  "eventId": "generated-uuid"
}

Triggering a Rule (Client → VMSC)

Fire a specific rule by its ID or name, bypassing the event trigger.

{
  "action": "triggerRule",
  "ruleId": "uuid-of-the-rule"
}

* Provide either ruleId or ruleName.

Subscribing to Events (Client → VMSC)

Request VMSC to forward all stream events (or a filtered subset) to your client.

{
  "action": "subscribe",
  "eventTypes": ["chat", "gift", "follow"],
  "sources": ["tiktok", "twitch"]
}

Event Broadcast (VMSC → Client)

After subscribing, VMSC forwards matching events to the client:

{
  "action": "event",
  "event": {
    "id": "uuid-v4",
    "type": "gift",
    "source": "tiktok",
    "timestamp": 1711900000000,
    "user": {
      "id": "12345",
      "username": "viewer1",
      "nickname": "Viewer One"
    },
    "data": {
      "giftName": "Rose",
      "giftId": 5655,
      "repeatCount": 1,
      "diamonds": 1
    }
  }
}

Error Messages (VMSC → Client)

{
  "action": "error",
  "code": "INVALID_ACTION",
  "message": "Unknown action: foobar"
}

Custom WebSocket Clients

In addition to acting as a server, VMSC can connect as a client to an external WebSocket endpoint to receive events. This is useful for integrating with custom bots or services that already run their own WebSocket server.

Configuration

1. Go to Settings > Integrations > Custom WebSocket > Client Connections.
2. Click Add Connection.
3. Enter the WebSocket URL of the external server (e.g., ws://localhost:9090).
4. Optionally provide an Auth Token to send as a header or query parameter.
5. Set the Source Name — this becomes the source value on events received from this connection.
6. Define a Message Mapping to tell VMSC how to extract event type, user, and data fields from the incoming JSON messages.
7. Click Save and toggle the connection on.

Example: Connecting a Custom Application

The following example shows how to connect a Node.js application to the VMSC custom WebSocket server, inject a custom event, and subscribe to all stream events.

const WebSocket = require("ws");

const AUTH_TOKEN = "your-vmsc-auth-token";
const ws = new WebSocket(`ws://localhost:7895?token=${AUTH_TOKEN}`);

ws.on("open", () => {
  console.log("Connected to VMSC");

  // Subscribe to all events from all platforms
  ws.send(JSON.stringify({
    action: "subscribe"
  }));

  // Inject a custom event
  ws.send(JSON.stringify({
    action: "injectEvent",
    event: {
      type: "chat",
      source: "my-app",
      user: {
        id: "bot-001",
        username: "MyApp",
        nickname: "My Application"
      },
      data: {
        message: "Automated message from my app"
      }
    }
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw);

  if (msg.action === "event") {
    console.log(`[${msg.event.source}] ${msg.event.type}:`,
      msg.event.data);
  }

  if (msg.action === "error") {
    console.error(`Error ${msg.code}: ${msg.message}`);
  }
});

ws.on("close", (code, reason) => {
  console.log(`Disconnected: ${code} ${reason}`);
});

Python Example

import asyncio
import json
import websockets

AUTH_TOKEN = "your-vmsc-auth-token"

async def main():
    uri = f"ws://localhost:7895?token={AUTH_TOKEN}"
    async with websockets.connect(uri) as ws:
        # Subscribe to gift events only
        await ws.send(json.dumps({
            "action": "subscribe",
            "eventTypes": ["gift"]
        }))

        # Listen for events
        async for raw in ws:
            msg = json.loads(raw)
            if msg["action"] == "event":
                event = msg["event"]
                print(f"Gift from {event['user']['username']}: "
                      f"{event['data']['giftName']}")

asyncio.run(main())

Best Practices

• Use specific subscriptions: Filter by eventTypes and sources to reduce unnecessary traffic.
• Handle reconnection: If your client disconnects, implement reconnection with exponential backoff. Re-send the subscribe message after reconnecting.
• Set a descriptive source name: When injecting events, use a meaningful source value so you can filter these events in the rule editor.
• Protect the auth token: Do not expose the token in client-side code or public repositories. Regenerate it in VMSC Settings if it is ever leaked.
• Rate limits: The server enforces a limit of 60 incoming messages per second per connection. Batch events if you need higher throughput.
• Test with the event log: After connecting, check the VMSC Dashboard event feed to confirm your injected events appear correctly.