websocket-realtime

name	websocket-realtime
description	Use the WebSocket connection in poll-builder to receive live vote updates. Use when you need to stream real-time poll results, monitor a poll for new votes, or build a live dashboard. Triggers include "live results", "real-time updates", "stream votes", "watch poll", or "WebSocket".

websocket-realtime

Receive live vote updates from poll-builder via WebSocket.

Connection

ws://localhost:3000/ws

Protocol

Subscribe to a poll

After connecting, send a subscribe message with the poll slug:

{ "type": "subscribe", "slug": "k9xm2q4r" }

Receive updates

The server sends an update message after each successful vote:

{
  "type": "update",
  "slug": "k9xm2q4r",
  "results": [
    { "optionId": 1, "text": "Mobile app",        "votes": 396, "pct": 48.1 },
    { "optionId": 2, "text": "API improvements",  "votes": 255, "pct": 31.0 },
    { "optionId": 3, "text": "Better docs",       "votes": 123, "pct": 14.9 },
    { "optionId": 4, "text": "Admin dashboard",   "votes": 50,  "pct": 6.1  }
  ],
  "totalVotes": 824
}

Unsubscribe

Close the connection or send:

{ "type": "unsubscribe", "slug": "k9xm2q4r" }

Example (Node.js)

import WebSocket from 'ws';

const ws = new WebSocket('ws://localhost:3000/ws');

ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'subscribe', slug: 'k9xm2q4r' }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === 'update') {
    console.log(`Total votes: ${msg.totalVotes}`);
    msg.results.forEach(r => {
      console.log(`  ${r.text}: ${r.votes} (${r.pct}%)`);
    });
  }
});

Multiple subscriptions

A single WebSocket connection can subscribe to multiple polls:

{ "type": "subscribe", "slug": "k9xm2q4r" }
{ "type": "subscribe", "slug": "7bwq1pz3" }

Each update message includes the slug field to identify which poll triggered it.

Error handling

If the slug does not exist:

{ "type": "error", "message": "poll_not_found", "slug": "k9xm2q4r" }

The connection remains open - you can subscribe to other slugs.

Notes

• Updates are broadcast only to clients subscribed to the relevant slug
• Closed polls do not generate updates (no new votes accepted)
• The WebSocket server is part of the same Node.js process as the HTTP server
• No authentication required for public WebSocket connections