Trigger API
The WebSocket protocol external tools use to fire events in Vfinity.
External programs can trigger Vfinity events over a WebSocket. Stream Deck plugins, Python scripts, Node servers and game integrations all use the same one-message protocol.
For a walkthrough with working server code, see Trigger Vfinity from your own app.
Roles
| Vfinity's role | Client. It connects out to a server you run |
| Protocol | JSON over WebSocket |
| Direction | Receive only. Vfinity listens and sends nothing back |
| Default address | localhost:8080 |
Message format
Vfinity expects text JSON frames.
{
"type": "trigger",
"name": "EVENT_NAME",
"data": {}
}| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Must be "trigger" |
name | string | Yes | Matched against the Trigger Name on your API mappings, case-insensitively |
data | object | No | Accepted and ignored. Reserved for later use |
Example
To fire the mapping whose trigger name is jump_scare:
{ "type": "trigger", "name": "jump_scare" }Setting it up in Vfinity
In SettingsConnections, on the Trigger API card, switch the API on.
Set WebSocket Host and WebSocket Port to your server. Defaults are localhost and 8080.
Click Connect API. The status turns green when the socket opens.
On the Events tab, create a mapping with Event Type set to API trigger and Trigger Name set to the name you will send.
Debugging
Turn on Verbose logging in SettingsPreferences and data, then open the debug console from the >_ button in the title bar. Verbose mode records raw WebSocket frames, so you can see exactly what arrived and how it parsed. Errors and warnings are always recorded whether verbose is on or not.
Common causes when a trigger does nothing:
- The socket is not connected. Your server has to be listening before Vfinity can connect.
- The names differ. Case is ignored; everything else is not.
- The mapping's toggle is off.
- The frame is not valid JSON, or
typeis not"trigger".