Skip to content

WebSocket protocol

Reference documentation for Pollux's WebSocket messaging.

sequenceDiagram
  participant Client
  participant Server
  participant Channel

  Client->>Server: HTTP Upgrade Request<br/>(with uuid)
  Server->>Client: 101 Switching Protocols
  Server->>Channel: subscribe(uuid)
  Server->>Client: current state (results / players)

  Note over Client,Channel: Live updates

  Server->>Channel: publish(event)
  Channel->>Client: event

  Note over Client,Channel: Disconnection

  Client--xServer: connection lost
  Server->>Channel: unsubscribe(uuid)

Connection

Static polls

ws://localhost:3000/ws?uuid=0194f1e0-...

Dynamic polls

ws://localhost:3000/ws/dynamic?uuid=0194f1e0-...

Quizzes

ws://localhost:3000/ws/quizz?uuid=0194f1e0-...&user=0194f1e0-...

The user parameter is required for quizzes to distinguish players.

Raffles

ws://localhost:3000/ws/raffle?uuid=0194f1e0-...

Events

Static polls

Sent on connection:

{ "result": [{ "choice": 0, "total": 5 }, { "choice": 1, "total": 3 }] }

Broadcast on vote:

{ "result": [{ "choice": 0, "total": 6 }, ...] }

Dynamic polls

Sent on connection (if a step exists):

{ "type": "step", "step": 0, "choices": ["Red", "Blue"] }
{ "type": "result", "step": 0, "result": [...] }

Broadcast on step creation:

{ "type": "step", "step": 1, "choices": ["Green", "Yellow"] }

Broadcast on vote:

{ "type": "result", "step": 0, "result": [...] }

Raffles

ws://localhost:3000/ws/raffle?uuid=0194f1e0-...

Sent on connection:

{ "type": "players", "players": [{ "user_id": "...", "pseudo": "Alice" }] }

If a winner already exists:

{ "type": "winner", "winnerId": "...", "winnerPseudo": "Alice" }

Admin broadcasts:

Event Trigger Payload
players Player registers { "type": "players", "players": [...] }
winner Admin spins wheel { "type": "winner", "winnerId": "...", "winnerPseudo": "Alice" }

Quizzes

Sent on connection:

{ "type": "players", "players": [{ "user_id": "...", "pseudo": "Alice" }] }

If a question is active:

{
  "type": "start",
  "step": 0,
  "choices": ["Paris", "London"],
  "question": "Which are capitals?",
  "correct": [0],
  "timer": 30,
  "startedAt": 1718200000000,
  "media": "https://example.com/image.jpg"
}
{
  "type": "result",
  "step": 0,
  "result": [{ "choice": 0, "total": 3 }, { "choice": 1, "total": 1 }]
}
{
  "type": "score",
  "step": 0,
  "scores": [{ "user_id": "...", "pseudo": "Alice", "score": 3, "total": 2 }]
}

Admin broadcasts:

Event Trigger Payload
start Admin starts question { "type": "start", "step": 0, "choices": [...], "timer": 30, "startedAt": ..., "correct": [...], "media": "..." }
result Vote submitted { "type": "result", "step": 0, "result": [...] }
score Vote submitted { "type": "score", "step": 0, "scores": [...] }
players Player registers { "type": "players", "players": [...] }
podium Admin triggers podium { "type": "podium", "scores": [...] }