WebSocket Realtime

Real-time presentation control, room management, and collaboration API

WebSocket Realtime API

Connect to for realtime presentation control and collaboration.

Connection

# WebSocket connections require a WebSocket client
# Using websocat for testing:
websocat "$WS_URL/ws?token=YOUR_ACCESS_TOKEN"

Room Management

Create Room

Create a new presentation room as host.

# Send via WebSocket connection
echo '{"type":"createRoom"}' | websocat "$WS_URL/ws?token=TOKEN"

Response:

{
  "type": "roomCreated",
  "payload": {
    "roomId": "ABC123",
    "socketId": "client_550e8400"
  }
}

Join Room

Join an existing presentation room.

echo '{"type":"joinRoom","payload":{"room":"ABC123","presenterName":"John","joinAsHost":false}}' | websocat "$WS_URL/ws?token=TOKEN"

Response:

{
  "type": "joinedRoom",
  "payload": {
    "id": "client_550e8400",
    "hosts": ["host_abc123"],
    "needsRefresh": false
  }
}

Slide Navigation

Control slide navigation in real-time.

EventDescriptionPayload
webActionNavigate slides{ action: 'next' | 'prev' | 'goto', slide?: number }
clicksEnabledToggle click control{ clicksEnabled: boolean }
countdownTimer control{ type: 'start' | 'stop', time: number }
presenterMouseLaser pointer{ mouse: { x: number, y: number }, color?: string }
needsRefreshRequest refresh{ forId: string }
refreshRoomRefresh all clients{ roomId: string }
# Next slide
echo '{"type":"webAction","payload":{"action":"next"}}' | websocat "wss://..."
# Previous slide
echo '{"type":"webAction","payload":{"action":"prev"}}' | websocat "wss://..."
# Go to slide 5
echo '{"type":"webAction","payload":{"action":"goto","slide":5}}' | websocat "wss://..."

Messaging

Send messages between hosts and clients.

# Message to hosts (from client)
echo '{"type":"messageToHosts","payload":{"text":"Question about slide 3"}}' | websocat "wss://..."
# Message to clients (from host)
echo '{"type":"messageToClients","payload":{"text":"Welcome everyone!"}}' | websocat "wss://..."

Incoming Message Format:

{
  "type": "messageFromHost",
  "payload": {
    "fromClientId": "host_abc123",
    "fromPresenterName": "Host",
    "originalPayload": { "text": "Welcome everyone!" }
  }
}

Event Reference

Outgoing Events (Client → Server)

EventDescription
createRoomCreate a new room
joinRoomJoin existing room
webActionSlide navigation
clicksEnabledToggle click control
countdownTimer control
presenterMouseLaser pointer position
messageToHostsSend message to hosts
messageToClientsSend message to clients (host only)
needsRefreshRequest refresh for specific client
refreshRoomRefresh all clients in room
closeStreamEnd presentation (host only)
logoutDisconnect from room

Incoming Events (Server → Client)

EventDescription
roomCreatedRoom creation confirmed
joinedRoomSuccessfully joined room
clientJoinedNew client joined room
webActionSlide navigation event
clicksEnabledClick control toggled
countdownTimer event
presenterMouseLaser pointer position
messageFromHostMessage from host
messageFromClientMessage from client
refreshRefresh requested
logoutDisconnection notice
errorError message

Copyright © 2026. All rights reserved.