WebSocket Realtime API

Establish a persistent connection for real-time counter events.

v2 WebSocket (Current)

Endpoint

wss://developers.counttogether.app/v2/ws?timezone=Europe/Berlin

Authorization: Bearer token header required.

wscat -c "wss://developers.counttogether.app/v2/ws?timezone=Europe/Berlin" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

Parameter	Required	Description
timezone	No	IANA timezone name. Date counter values are pre-resolved for this timezone. Falls back to the user's account timezone.

Protocol

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

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

jsonrpc: always "2.0"
method: event identifier (see below)
params: event-specific payload (camelCase)

Ignore unknown methods or fields for forward compatibility.

v2 Events

counterUpdated

Emitted when a counter value or metadata changes.

For UpDown counters:

{
  "jsonrpc": "2.0",
  "method": "counterUpdated",
  "params": {
    "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a111",
    "name": "Daily Steps",
    "type": "UpDown",
    "value": 12500
  }
}

For FromDate/ToDate counters, value is the timezone-resolved day count (pastDays or remainingDays):

{
  "jsonrpc": "2.0",
  "method": "counterUpdated",
  "params": {
    "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a222",
    "name": "Running Streak",
    "type": "FromDate",
    "value": 46
  }
}

counterDeleted

Counter removed or no longer accessible.

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

counterMemberlistChanged

Member list changed (added/removed member).

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

Ordering & Delivery

Order preserved per connection.
No exactly-once guarantee; client logic must be idempotent.

Reconnect Strategy

Use exponential backoff (1s, 2s, 5s, 10s, 30s) and re-sync via GET /v2/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.

v1 WebSocket (Deprecated)

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

The v1 WebSocket emits the same event names (counterUpdated, counterDeleted, counterMemberlistChanged) but with a nested data payload (matching the v1 REST response shape) instead of a flat value.

21 April 2026