Realtime WebSocket API

Subscribe to live job events for your VTC: when a member starts a job, delivers cargo, or cancels. Same VTC API token as REST API v1 (create in tracksy.tr → VTC → Edit → API).

Connection

Plain WebSocket, JSON text frames. Connect, authenticate immediately, then listen for job_event messages.

1. Open WebSocket to the URL above.
2. Send { "op": "auth", "token": "…" } with your 64-character hex VTC API token.
3. Wait for auth_ok.
4. Send ping every heartbeat_sec (default 30s).

Authentication

Client → server (first message after connect):

{
  "op": "auth",
  "token": "YOUR_VTC_API_TOKEN_64_HEX"
}

Server → client on success:

{
  "op": "auth_ok",
  "vtc_id": 1,
  "vtc_name": "Your VTC",
  "heartbeat_sec": 30
}

On failure: auth_error then connection may close with code 4001.

Heartbeat

Client → server:

{ "op": "ping" }

Server → client:

{ "op": "pong", "at": "2026-05-30T12:00:00.000Z" }

Job events

After auth_ok, you receive events for drivers in your VTC only.

Server → client:

{
  "op": "job_event",
  "event": "job.delivered",
  "at": "2026-05-30T12:00:00+00:00",
  "vtc_id": 1,
  "driver": {
    "user_id": 12,
    "steam_id": "76561198000000000",
    "display_name": "Driver"
  },
  "job": {
    "delivery_id": 999,
    "source_city": "Berlin",
    "destination_city": "Hamburg",
    "cargo_name": "Logs",
    "distance_driven_km": 412.5,
    "earned_money": 12400
  }
}

job fields vary by event; started/cancelled include route/cargo hints; delivered includes metrics when available.

Message reference

Client → server

Server → client

Examples

Browser / Node (ws package)

const WebSocket = require('ws'); // or global WebSocket in browser

const ws = new WebSocket('wss://realtime.tracksy.tr/');

ws.on('open', () => {
  ws.send(JSON.stringify({
    op: 'auth',
    token: process.env.TRACKSY_VTC_TOKEN
  }));
});

ws.on('message', (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.op === 'auth_ok') {
    setInterval(() => ws.send(JSON.stringify({ op: 'ping' })), msg.heartbeat_sec * 1000);
  }
  if (msg.op === 'job_event') {
    console.log(msg.event, msg.driver.display_name, msg.job);
  }
});

Python (websocket-client)

import json, os, time, websocket

TOKEN = os.environ["TRACKSY_VTC_TOKEN"]
URL = "wss://realtime.tracksy.tr/"

def on_message(ws, message):
    msg = json.loads(message)
    if msg.get("op") == "auth_ok":
        ws.send(json.dumps({"op": "ping"}))
    if msg.get("op") == "job_event":
        print(msg["event"], msg["driver"]["display_name"])

ws = websocket.WebSocketApp(
    URL,
    on_open=lambda w: w.send(json.dumps({"op": "auth", "token": TOKEN})),
    on_message=on_message,
)
ws.run_forever(ping_interval=25)

REST vs Realtime

Operations: health check (public JSON). Internal publish endpoint is server-only (not for integrators).