The Client API

The earlier modules explained what a WebSocket is. This module is about the one object the browser hands you to drive it: the global WebSocket class. It is surprisingly small — a constructor, four events, one state field, and two methods do almost everything you will ever need.

The whole API on one screen

There is no framework to learn here, only a single built-in class. Here it is in its entirety, as a sketch:

// Open a connection. This one line is the whole "setup".
const ws = new WebSocket('wss://example.com/socket');

// Four events — the only places your code reacts.
ws.onopen = () => console.log('connected');
ws.onmessage = (event) => console.log('got', event.data);
ws.onerror = (event) => console.log('something went wrong');
ws.onclose = (event) => console.log('closed', event.code);

// One state field, and two methods.
ws.readyState; // 0 CONNECTING, 1 OPEN, 2 CLOSING, 3 CLOSED
ws.send('a message');
ws.close();

That is it. Everything else in this module is detail and nuance layered on top of those few members. If you can read the snippet above, you already know the shape of every browser WebSocket program.

The lifecycle as a state machine

A connection is never just “on” or “off”. It moves through four distinct states, in one direction only, from CONNECTING to CLOSED. The diagram below is the map you will keep returning to:

stateDiagram-v2
  [*] --> CONNECTING: new WebSocket(url)
  CONNECTING --> OPEN: handshake succeeds (onopen)
  CONNECTING --> CLOSED: handshake fails (onerror, onclose)
  OPEN --> CLOSING: close() called or peer closes
  CLOSING --> CLOSED: closing handshake done (onclose)
  OPEN --> CLOSED: connection drops
  CLOSED --> [*]

The WebSocket connection lifecycle

Read it as a story: you construct the object and it is CONNECTING. If the handshake succeeds it becomes OPEN and fires onopen — this is the only state in which you may send. When you or the peer asks to close, it passes briefly through CLOSING, then settles in CLOSED and fires onclose. A connection never goes backwards; a closed socket is closed forever, and reconnecting means constructing a brand-new object.

What this module covers

These five lessons walk the API in the order you actually meet it:

The Client API (you are here) — the object at a glance and its lifecycle.
Creating a connection — the constructor, ws:// vs wss://, and subprotocols.
Events and readyState — the four events and the four states they reflect.
Sending and receiving — send(), the message event, ordering, and when you may speak.
Binary data — text vs binary, binaryType, and sending bytes.

See the lifecycle run

The demo below uses an in-page echo socket with the real WebSocket API — same onopen, onmessage, send, close — so it runs anywhere with no server. In a real app the only line that changes is the first, new WebSocket('wss://your-server'). Press Run and watch a single connection move through its states.

JavaScript

(function () {
  // In-page echo socket with the same API as a real WebSocket.
  // In a real app: const ws = new WebSocket('wss://your-server').
  const names = ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'];
  class EchoSocket {
    constructor() {
      this.readyState = 0;
      setTimeout(() => {
        this.readyState = 1;
        if (this.onopen) this.onopen({});
        if (this.onmessage) this.onmessage({ data: 'connected — send me anything' });
      }, 50);
    }
    send(data) { setTimeout(() => { if (this.onmessage) this.onmessage({ data: data }); }, 50); }
    close(code) { this.readyState = 2; setTimeout(() => { this.readyState = 3; if (this.onclose) this.onclose({ code: code || 1000 }); }, 10); }
  }

  const ws = new EchoSocket();
  console.log('state after construct:', names[ws.readyState]);
  ws.onopen = () => {
    console.log('state on open:', names[ws.readyState]);
    ws.send('hello');
  };
  ws.onmessage = (event) => {
    console.log('received:', event.data);
    ws.close();
    console.log('state right after close():', names[ws.readyState]);
  };
  ws.onclose = (event) => console.log('state on close:', names[ws.readyState], '- code', event.code);
})();

Notice the printed states march forward only: CONNECTING, then OPEN, then CLOSING the instant we call close(), and finally CLOSED. That one-way march is the heartbeat of every WebSocket program.