WebSocket API

The WebSocket API provides a persistent connection for receiving real-time events and sending actions. It is the primary data interface used by the TRCR web application and supports all operations available via REST.

Connection Flow

WebSocket authentication uses a ticket-based system. First obtain a short-lived ticket via REST, then present it when connecting.

Step 1: Get a WebSocket Ticket

POST https://api.trcr.pro/api/v1/auth/ws-ticket
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:
{ "ticket": "wst_a1b2c3d4e5f6..." }

Tickets expire after 30 seconds and can only be used once.

Step 2: Connect and Authenticate

Open a WebSocket connection and immediately send an authentication message:

import WebSocket from "ws";

const ws = new WebSocket("wss://api.trcr.pro/ws");

ws.on("open", () => {
  // Authenticate with the ticket
  ws.send(JSON.stringify({
    action: "authenticate",
    payload: { ticket: "wst_a1b2c3d4e5f6..." },
    request_id: "req_1"
  }));
});

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

  if (msg.request_id === "req_1" && msg.status === "ok") {
    console.log("Authenticated successfully");
  }

  // Handle real-time events
  if (msg.event) {
    console.log("Event:", msg.event, msg.data);
  }
});

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

ws.on("error", (err) => {
  console.error("WebSocket error:", err);
});

Message Format

All messages are JSON objects. Client-to-server messages follow this structure:

{
  "action": "string",         // The action to perform
  "payload": { ... },         // Action-specific data
  "request_id": "string"      // Optional: correlate with response
}

Server Responses

For request/response actions, the server replies with:

{
  "status": "ok" | "error",   // Result status
  "data": { ... },            // Response data (on success)
  "error": {                  // Error details (on failure)
    "code": "string",
    "message": "string"
  },
  "request_id": "string"      // Matches your request_id
}

Server Events (Push)

Real-time events are pushed without a request_id:

{
  "event": "string",          // Event type
  "data": { ... }             // Event payload
}

Real-Time Events

After authentication, you automatically receive events for entities you have access to. No subscription is needed.

EntityChanged

Fired whenever any entity is created, updated, or deleted. This is the most common event.

{
  "event": "EntityChanged",
  "data": {
    "entity_type": "task",           // task, project, time_entry, invoice, etc.
    "entity_id": "tsk_abc123",
    "action": "updated",             // created, updated, deleted
    "changes": {                     // Only present on "updated"
      "status": { "from": "open", "to": "done" }
    },
    "entity": { ... },              // Full entity data
    "user_id": "usr_xyz",           // User who made the change
    "timestamp": "2026-03-28T14:30:00Z"
  }
}

ChatMessage

Fired when a new chat message is sent to a channel you belong to.

{
  "event": "ChatMessage",
  "data": {
    "channel_id": "ch_abc123",
    "message": {
      "id": "msg_001",
      "content": "Hello team!",
      "user_id": "usr_xyz",
      "user_name": "Jane Doe",
      "created_at": "2026-03-28T14:30:00Z"
    }
  }
}

NotificationCreated

Fired when a new notification is created for the user.

{
  "event": "NotificationCreated",
  "data": {
    "id": "ntf_001",
    "type": "task_assigned",
    "title": "You were assigned to 'Implement login page'",
    "entity_type": "task",
    "entity_id": "tsk_abc123",
    "created_at": "2026-03-28T14:30:00Z"
  }
}

TimerUpdate

Fired when the current user starts or stops a timer from another device or tab.

{
  "event": "TimerUpdate",
  "data": {
    "running": true,
    "time_entry": {
      "id": "te_abc123",
      "description": "Working on API docs",
      "project_id": "prj_abc",
      "start_time": "2026-03-28T14:00:00Z"
    }
  }
}

UserPresence

Fired when a team member comes online or goes offline.

{
  "event": "UserPresence",
  "data": {
    "user_id": "usr_xyz",
    "status": "online",        // online, away, offline
    "last_seen": "2026-03-28T14:30:00Z"
  }
}

Action Reference

The following actions can be sent over WebSocket. They mirror the REST API endpoints.

Authentication

Tasks

Projects

Task Groups

Task Statuses

Task Recurrences

Organizations

Members

Time Entries

Invoices

Clients

Chat

Search

Notifications

Reports

Labels

Milestones

Sidebar

Dashboard

Audit

Heartbeat / Keep-Alive

The server sends a ping frame every 30 seconds. If your WebSocket library does not automatically respond with a pong, you must handle it manually. If no pong is received within 10 seconds, the server closes the connection.

You can also send a ping action to test the connection:

{ "action": "ping" }

// Response:
{ "action": "pong", "timestamp": "2026-03-28T14:30:00Z" }

Reconnection

Connections may be dropped due to network issues, server deployments, or inactivity. Implement automatic reconnection with exponential backoff:

function connect(attempt = 0) {
  const ws = new WebSocket("wss://api.trcr.pro/ws");

  ws.on("open", () => {
    attempt = 0;
    // Re-authenticate with a fresh ticket
    authenticateWs(ws);
  });

  ws.on("close", () => {
    const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
    console.log(`Reconnecting in ${delay}ms...`);
    setTimeout(() => connect(attempt + 1), delay);
  });

  ws.on("error", () => {
    ws.close();
  });

  return ws;
}

Rate Limits

WebSocket connections are limited to 60 messages per minute. If you exceed this limit, the server sends an error message and may close the connection.

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many messages. Please slow down."
  }
}

Connection Limits

• Maximum 5 concurrent WebSocket connections per user
• Maximum message size: 64 KB
• Idle connections (no messages for 5 minutes) are closed
• Authentication must complete within 10 seconds of connecting