What a Subprotocol Actually Is
The base WebSocket protocol only defines how bytes are framed and how a connection opens and closes — it says nothing about what the payloads inside those frames mean. A subprotocol is an agreed-upon convention layered on top, such as the message format, field names, and interaction rules two parties will use, and it is negotiated during the handshake itself via the Sec-WebSocket-Protocol header, which the client sends as a comma-separated list of protocol names it supports and the server echoes back with the single one it has chosen to use, or omits entirely if it doesn't support any of them.
Cricket analogy: It's like two boards agreeing before a bilateral series whether they'll play under ICC playing conditions or a domestic variant with different powerplay rules — the pitch and stumps (the transport) are the same, but the rulebook governing play differs.
Negotiating a Subprotocol During the Handshake
The negotiation is intentionally simple: the client lists every subprotocol it's willing to speak, ordered by preference, and the server picks at most one from that list — it cannot invent a new name the client never offered, and it cannot select more than one. If the server includes a Sec-WebSocket-Protocol header in its 101 response, the client must treat the connection as using exactly that subprotocol; if the header is absent from the response, no subprotocol was agreed and the application must fall back to some default understanding or fail. This is commonly used to version an API (offering chat.v1 and chat.v2 simultaneously) or to let one WebSocket endpoint serve multiple distinct client types, like graphql-ws for GraphQL subscriptions versus a custom JSON protocol for a different feature.
Cricket analogy: It's like a toss-winning captain choosing to bat or bowl from the exact two options the coin toss presents — there's no third option to invent, and once chosen, both teams play the rest of the match under that single decision.
// Client offers two subprotocols, in preference order
const socket = new WebSocket('wss://api.example.com/ws', ['chat.v2', 'chat.v1']);
socket.addEventListener('open', () => {
// The server picked exactly one; inspect it to know how to speak
console.log('Negotiated subprotocol:', socket.protocol); // e.g. "chat.v1"
if (socket.protocol === 'chat.v2') {
socket.send(JSON.stringify({ v: 2, type: 'hello' }));
} else if (socket.protocol === 'chat.v1') {
socket.send(JSON.stringify({ type: 'hello' }));
} else {
// Empty string means the server didn't agree to any subprotocol
socket.close(1002, 'No compatible subprotocol');
}
});Subprotocols vs. Extensions
It's easy to conflate subprotocols with extensions, but they solve different problems: extensions (negotiated via Sec-WebSocket-Extensions, like permessage-deflate) modify how frames themselves are transported — compression, multiplexing — and are meant to be transparent to the application layer, whereas a subprotocol defines what the application-level messages mean and is meaningful only to the application code, not the WebSocket implementation itself. A server can support several extensions and several subprotocols independently, and a client library like the browser's WebSocket constructor lets you specify subprotocols directly but has no way to request specific extensions, since those are typically handled transparently by the underlying implementation.
Cricket analogy: It's like the difference between the type of ball used (a transport-level detail affecting how the game physically plays, similar to an extension) versus the specific match format and points system being contested (an application-level agreement, similar to a subprotocol) — both matter, but they operate at different levels.
If your server supports multiple subprotocols but a client connects offering none (an empty array, or simply new WebSocket(url) with no second argument), the server must not send a Sec-WebSocket-Protocol header back. Code that blindly reads socket.protocol without checking for an empty string will misbehave — always verify the negotiated value before assuming a specific message format.
- A subprotocol is an application-level messaging convention negotiated on top of the raw WebSocket framing protocol.
- The client offers a comma-separated, preference-ordered list via Sec-WebSocket-Protocol; the server picks at most one.
- If the server's 101 response omits Sec-WebSocket-Protocol, no subprotocol was agreed and the connection has no negotiated convention.
- Subprotocols are commonly used for API versioning or to let one endpoint serve multiple distinct client types.
- Extensions (like permessage-deflate) modify frame transport and are transparent to application code, unlike subprotocols.
- Browser WebSocket clients can request subprotocols via the constructor's second argument but cannot request extensions directly.
- Code should always check the negotiated socket.protocol value rather than assuming a subprotocol was accepted.
Practice what you learned
1. What header is used to negotiate a WebSocket subprotocol during the handshake?
2. How many subprotocols can a server select from the client's offered list?
3. What does it mean if the server's 101 response does not include a Sec-WebSocket-Protocol header?
4. What is the key difference between a WebSocket extension and a subprotocol?
5. Which is a typical real-world use of WebSocket subprotocols?
Was this page helpful?
You May Also Like
Text and Binary Frames
How WebSocket messages are broken into frames, and the difference between UTF-8 text frames and raw binary frames.
Opening and Closing Connections
How a WebSocket connection is established through the HTTP upgrade handshake and gracefully terminated using the closing handshake.
Close Codes and Error Handling
What WebSocket close codes mean, how to choose the right one, and how to build robust reconnect and error-handling logic around them.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics
Web DevelopmentNext.js Study Notes
JavaScript · 30 topics