WebSocket API (for Advanced Users)

This page is for advanced users who want to connect other tools to Vfinity. If you are just starting out, you can skip this page for now.

What is the WebSocket API?

The WebSocket API lets other apps talk to Vfinity. For example:

• A Stream Deck button can trigger events
• A Python script can send commands
• Your own custom app can control Vfinity

When would you use this?

You might want to use this if:

• You have a Stream Deck and want buttons to trigger Vfinity events
• You are writing a script to automate things
• You are building a custom integration
• You want to trigger events from outside of TikTok LIVE

How it works

Vfinity acts as a client that connects to a server you set up. Here is the flow:

1. You run a WebSocket server on your computer
2. Vfinity connects to your server
3. Your server sends JSON messages to Vfinity
4. Vfinity receives the messages and triggers events

Setup steps

Step 1: Turn on the API in Vfinity

1. Open Vfinity
2. Go to the Connections tab
3. Find the Generic API section
4. Turn on the switch that says Enable API WebSocket

Step 2: Enter connection details

1. WebSocket Host: Usually localhost if the server is on the same computer
2. WebSocket Port: Default is 8080, but you can change it
3. Click Connect API

Step 3: Check the connection

If it worked, you will see a green light or "Connected" status.

Step 4: Create a trigger event

1. Go to the Events tab
2. Click New Event
3. Set Event Type to API Trigger
4. Enter a Trigger Name (like my_event)
5. Set up the action you want (hotkey, move, VFX, etc.)
6. Click Add Mapping

The JSON message format

Your server sends messages to Vfinity in JSON format. Here is what the message looks like:

{
  "type": "trigger",
  "name": "EVENT_NAME",
  "data": {}
}

What each part means:

• type: Always set this to "trigger"
• name: The name of your event (must match what you set up in Vfinity)
• data: Optional extra information (you can leave this empty for now)

Example: Trigger an event called "jump"

{
  "type": "trigger",
  "name": "jump"
}

When Vfinity receives this message, it will trigger the event named "jump" that you set up.

Server examples

Since Vfinity connects to your server, you need to run a server first. Here are simple examples in Node.js and Python.

Node.js example

You need the ws library. Install it with: npm install ws

const WebSocket = require("ws");

// Start a server on port 8080
const wss = new WebSocket.Server({ port: 8080 });

console.log("WebSocket server started on port 8080");

wss.on("connection", (ws) => {
  console.log("Vfinity connected!");

  // Send a trigger every 5 seconds
  setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      const payload = {
        type: "trigger",
        name: "test_trigger",
      };

      console.log("Sending trigger:", payload);
      ws.send(JSON.stringify(payload));
    }
  }, 5000);

  ws.on("close", () => {
    console.log("Vfinity disconnected");
  });
});

Python example

You need the websockets library. Install it with: pip install websockets

import asyncio
import websockets
import json

async def handler(websocket):
    print("Vfinity connected!")
    try:
        while True:
            # Ask user what to trigger
            trigger_name = await asyncio.to_thread(input, "Enter trigger name (or 'quit'): ")

            if trigger_name.lower() == 'quit':
                break

            payload = {
                "type": "trigger",
                "name": trigger_name
            }

            await websocket.send(json.dumps(payload))
            print(f"Sent: {payload}")

    except websockets.ConnectionClosed:
        print("Vfinity disconnected")

async def main():
    async with websockets.serve(handler, "localhost", 8080):
        print("WebSocket server started on port 8080")
        await asyncio.get_running_loop().create_future()

if __name__ == "__main__":
    asyncio.run(main())

Troubleshooting

Status stays on "Connecting":

• Make sure your server is running
• Check that the port number matches
• Try restarting both the server and Vfinity

Triggers are not working:

• Check that the trigger name in your JSON matches the name in Vfinity exactly
• Make sure the type is set to "trigger"
• Turn on Debug Mode in Settings and press F12 to see detailed logs

That is it!

The WebSocket API is powerful but simple once you get it working. You can now control Vfinity from any external tool or script.