How is a WebSocket subprotocol negotiated?

In the opening handshake the client sends a Sec-WebSocket-Protocol request header listing one or more subprotocol tokens it supports, in order of preference. The server picks at most one it also supports and echoes that single value in its Sec-WebSocket-Protocol response header. If the server omits the header, no subprotocol is in effect.

What happens if the server does not support any offered subprotocol?

The server should complete the handshake without a Sec-WebSocket-Protocol response header, meaning the connection uses no application subprotocol. A strict client that requires one may then close the connection. The server must never select a subprotocol the client did not offer.

Where do these names come from?

Subprotocol identifiers are coordinated in the IANA WebSocket Subprotocol Name Registry so that independent implementations agree on a token. Registered names like mqtt, wamp.2.json and stomp map to a specific message format and defining specification, avoiding clashes between unrelated protocols.

Are subprotocol names case-sensitive?

Yes. The tokens are compared exactly, so you must use the registered casing — for example v12.stomp, not V12.STOMP. They are also opaque tokens, not MIME types, even when they resemble versioned dotted strings like wamp.2.json.

Can I use an unregistered subprotocol name?

Technically yes — any token valid per the HTTP field grammar works between a client and server that agree on it privately. But for public or interoperable protocols you should register the name with IANA to prevent collisions and signal a stable, documented meaning to other implementers.

WebSocket Subprotocol Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

WebSocket subprotocols

A raw WebSocket connection just moves opaque frames; a subprotocol defines the application-level message format running over it — MQTT, STOMP, WAMP, GraphQL subscriptions and more. The client and server agree on one during the handshake using the Sec-WebSocket-Protocol header. This reference lists common IANA-registered subprotocol identifiers with their purpose.

How it works

The client lists the subprotocols it supports, most-preferred first; the server selects exactly one and echoes it back:

GET /chat HTTP/1.1
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Protocol: graphql-transport-ws, graphql-ws

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Protocol: graphql-transport-ws

The chosen token must be one the client offered, compared with exact casing. If the server returns no Sec-WebSocket-Protocol header, the connection runs with no application subprotocol. Names are coordinated in the IANA registry so independent implementations interoperate.

Tips and notes

List subprotocols in preference order; the server picks the first it supports.
Tokens are case-sensitive and opaque — use the exact registered string.
A server must never select a subprotocol the client did not offer.
For public protocols, register the name with IANA to avoid collisions.