Area 08 · Backend · Concept 05 of 20

WebSockets

A two-way live connection, for voice, real-time chat and collaboration.

01–10 · The basePhase 0 + 5 · Weeks 1–2, 18–20≈ 1 hour

The idea

WebSockets upgrade an HTTP connection into a persistent two-way channel. Both sides can send messages at any time, with low overhead. That suits real-time voice (audio chunks both ways), multiplayer collaboration, live agent control (pause, cancel, approve mid-run) and presence.

They are more work than SSE: you handle connection state, reconnection, authentication on connect, heartbeats and scaling (connections are sticky to a server, so you often need a pub/sub layer like Redis to broadcast across instances).

Rule of thumb: use SSE for server-to-client streaming of text; use WebSockets when the client must also send a continuous stream or interrupt in real time.

Why it matters

Realtime voice agents and collaborative AI tools are built on WebSockets or WebRTC.

Words to know

  • UpgradeSwitching an HTTP connection to the WebSocket protocol.
  • Sticky sessionA client stays connected to the same server.

Try it without code

Open a socket

  1. Run the server below.
  2. In the browser console run: ws = new WebSocket("ws://localhost:8000/ws"); ws.onmessage = e => console.log(e.data); ws.send("hi")

Use it in code

A WebSocket chat endpoint that supports cancel mid-generation.

python
import asyncio, anthropic
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()
client = anthropic.AsyncAnthropic()

@app.websocket("/ws")
async def ws_chat(ws: WebSocket):
    await ws.accept()
    task = None
    async def answer(q):
        async with client.messages.stream(model="claude-haiku-5-5", max_tokens=400,
                                          messages=[{"role": "user", "content": q}]) as s:
            async for text in s.text_stream:
                await ws.send_json({"delta": text})
        await ws.send_json({"done": True})
    try:
        while True:
            msg = await ws.receive_text()
            if msg == "/cancel" and task:
                task.cancel(); await ws.send_json({"cancelled": True})
            else:
                task = asyncio.create_task(answer(msg))
    except WebSocketDisconnect:
        if task: task.cancel()
PRACTICE · TICK IT AFTER THIS

Add a "stop generating" button to a chat page using this endpoint.

Common mistakes

  • No auth check on connect.
  • Assuming one server when you scale to several.

Go deeper