Realtime & WebSockets
Native WebSocket Server (/ws)
Connect to the native browser WebSocket server at /ws. Features room multiplexing, peer-to-peer event broadcasts, typing indicators, and an automated @bot assistant simulator without external socket dependencies.
Realtime WebSocket PubSub & SSE Fallback Architecture
Realtime Protocol
Click to expand full architecture
Full-duplex bidirectional event bus: Connection upgrade, channel subscription, presence echo bots, and HTTP SSE fallback.
1HTTP 101 Upgrade
WebSocket Handshake
Client establishes persistent ws:// or wss:// connection passing session identity.
2Multiplexing
Channel PubSub & Bots
Subscribe to rooms (#general, #support) with automated AI bot responses.
3SSE Resilient
SSE Fallback Stream
Server-Sent Events fallback for environments blocking persistent WebSocket frames.
ws://localhost:3001/wsdisconnected
Quick Payloads:
[12:00:00]System:WebSocket client ready. Click "Connect Live WS" to establish a persistent full-duplex session.
WebSocket Protocol Frame Specification
The Playground WebSocket gateway parses standardized JSON envelope payloads:
| Frame Type | Direction | Payload Example | Description |
|---|---|---|---|
| join | Client → Server | {"type":"join","room":"general"} | Subscribes socket to a specific channel (e.g. general, support, custom). |
| chat | Client → Server | {"type":"chat","text":"Hello"} | Broadcasts a chat message to all peers in the current active room. |
| typing | Bidirectional | {"type":"typing","isTyping":true} | Emits keystroke typing bubble to room peers without persisting to database. |
| message | Server → Client | {"type":"message","id":"msg-..","text":".."} | Inbound server broadcast dispatched to subscribers with timestamp and sender ID. |
Client Integration Code
Production-grade integration patterns for Vanilla JS and React / Next.js hooks:
1
// Native WebSocket Connection (Vanilla JavaScript)
2
const wsUrl = 'ws://localhost:3001/ws';
3
const ws = new WebSocket(wsUrl);
4
5
ws.onopen = () => {
6
console.log('Connected to Playground API WebSocket server');
7
8
// 1. Join room
9
ws.send(JSON.stringify({ type: 'join', room: 'general' }));
10
11
// 2. Send public message
12
ws.send(JSON.stringify({ type: 'chat', text: 'Hello from client!' }));
13
};
14
15
ws.onmessage = (event) => {
16
const frame = JSON.parse(event.data);
17
console.log('Received frame:', frame);
18
};
19
20
ws.onclose = (event) => {
21
console.warn('Disconnected:', event.reason);
22
};