WebSocket Realtime API

Establish a persistent connection for real-time counter events.

Endpoint

wss://developers.counttogether.app/v1/ws

Authorization: Bearer token header required.

Example:

wscat -c wss://developers.counttogether.app/v1/ws -H "Authorization: Bearer YOUR_TOKEN"

Protocol

Server -> client messages follow JSON-RPC 2.0 notification format (no id).

{
  "jsonrpc": "2.0",
  "method": "counterUpdated",
  "params": { }
}

Fields:

jsonrpc: always "2.0"
method: event identifier (values below)
params: object with event-specific fields (camelCase)

Unknown methods or fields MUST be ignored for forward compatibility.

Events

counterUpdated

Complete state change (value and/or metadata) of a counter.

{
  "jsonrpc": "2.0",
  "method": "counterUpdated",
  "params": {
    "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a111",
    "displayName": "Daily Steps",
    "data": { "value": 12500, "mode": "UpAndDown" }
  }
}

Params:

counterId (UUID)
displayName (string, optional if unchanged)
data (object|null; see Data Models)

counterDeleted

Counter removed or no longer accessible.

{
  "jsonrpc": "2.0",
  "method": "counterDeleted",
  "params": { "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a111" }
}

Params:

counterId (UUID)

counterMemberlistChanged

Member list changed (added/removed member).

{
  "jsonrpc": "2.0",
  "method": "counterMemberlistChanged",
  "params": { "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a111" }
}

Params:

counterId (UUID)

Ordering & Delivery

Order preserved per connection.
No exactly-once guarantee; client logic must be idempotent.
Duplicate semantic updates (e.g. multiple counterUpdated with same data) should be coalesced by client.

Reconnect Strategy

Use exponential backoff (1s,2s,5s,10s,30s) and re-sync via GET /v1/counters after reconnect to cover missed events.

Compatibility

Additional methods may appear at any time.
Ignore unknown methods and params fields.

Security

One authenticated user per socket.
The access token is never included in message payloads.

Last modified: 01 October 2025