Skip to main content
The WebSocket API enables bidirectional communication between clients and servers over a single TCP connection.

​
WebSocket

Represents a WebSocket connection.

​
Constructor

new WebSocket(
  url: string | URL,
  protocols?: string | string[]
)
​
url
string | URL
required
The URL to connect to. Must use ws: or wss: protocol.
​
protocols
string | string[]
Optional subprotocol(s) to negotiate.

​
Constants

​
WebSocket.CONNECTING
0
Connection is being established.
​
WebSocket.OPEN
1
Connection is established and ready to communicate.
​
WebSocket.CLOSING
2
Connection is closing.
​
WebSocket.CLOSED
3
Connection is closed.

​
Properties

​
url
string
The URL of the WebSocket connection.
​
readyState
number
Current state of the connection (0-3, see constants above).
​
protocol
string
Negotiated subprotocol.
​
extensions
string
Negotiated extensions.
​
bufferedAmount
number
Number of bytes queued for transmission.
​
binaryType
'arraybuffer' | 'blob'
Type for binary data. Default is 'arraybuffer'.

​
Event handlers

​
onopen
EventHandler
Called when the connection is established.
websocket.onopen = (event: Event) => {
  console.log('Connection opened');
};
​
onmessage
EventHandler
Called when a message is received.
websocket.onmessage = (event: MessageEvent) => {
  console.log('Received:', event.data);
};
​
onerror
EventHandler
Called when an error occurs.
websocket.onerror = (event: Event) => {
  console.error('WebSocket error');
};
​
onclose
EventHandler
Called when the connection is closed.
websocket.onclose = (event: CloseEvent) => {
  console.log('Closed:', event.code, event.reason);
};

​
Methods

​
send()
method
Send data through the WebSocket.
send(data: string | ArrayBuffer | ArrayBufferView | Blob): void
​
close()
method
Close the WebSocket connection.
close(code?: number, reason?: string): void
  • code: Optional close code (default: 1000)
  • reason: Optional close reason (max 123 bytes UTF-8)
​
addEventListener()
method
Add an event listener.
addEventListener(
  type: 'open' | 'message' | 'error' | 'close',
  listener: EventListener
): void
​
removeEventListener()
method
Remove an event listener.
removeEventListener(
  type: string,
  listener: EventListener
): void

​
WebSocketPair

Create a pair of WebSocket objects that are connected to each other.

​
Constructor

new WebSocketPair()

​
Properties

​
0
WebSocket
First WebSocket of the pair.
​
1
WebSocket
Second WebSocket of the pair.

​
MessageEvent

Event object for WebSocket messages.
​
data
string | ArrayBuffer | Blob
The message data.
​
type
'message'
Event type.

​
CloseEvent

Event object for WebSocket close events.
​
code
number
Close status code.
​
reason
string
Close reason.
​
wasClean
boolean
True if the connection closed cleanly.

​
Close codes

​
1000
Normal Closure
Normal closure; the connection successfully completed.
​
1001
Going Away
Endpoint is going away (e.g., server shutdown).
​
1002
Protocol Error
Endpoint terminating due to protocol error.
​
1003
Unsupported Data
Endpoint terminating due to unsupported data type.
​
1005
No Status Received
Reserved; indicates no status code was provided.
​
1006
Abnormal Closure
Reserved; indicates connection closed abnormally.
​
1007
Invalid Payload
Endpoint terminating due to inconsistent message data.
​
1008
Policy Violation
Endpoint terminating due to policy violation.
​
1009
Message Too Big
Endpoint terminating due to message too large.
​
1010
Mandatory Extension
Client terminating due to missing expected extension.
​
1011
Internal Error
Server terminating due to unexpected condition.
​
1015
TLS Handshake
Reserved; indicates TLS handshake failure.

​
Example usage

​
Client-side WebSocket

const ws = new WebSocket('wss://example.com/socket');

ws.addEventListener('open', (event) => {
  console.log('Connected');
  ws.send('Hello Server!');
});

ws.addEventListener('message', (event) => {
  console.log('Received:', event.data);
});

ws.addEventListener('close', (event) => {
  console.log('Disconnected:', event.code, event.reason);
});

ws.addEventListener('error', (event) => {
  console.error('Error');
});

​
Server-side WebSocket (Cloudflare Workers)

export default {
  async fetch(request, env, ctx) {
    // Upgrade to WebSocket
    const upgradeHeader = request.headers.get('Upgrade');
    if (upgradeHeader !== 'websocket') {
      return new Response('Expected WebSocket', { status: 400 });
    }

    const pair = new WebSocketPair();
    const [client, server] = Object.values(pair);

    // Handle server-side events
    server.accept();
    server.addEventListener('message', (event) => {
      console.log('Received from client:', event.data);
      server.send('Echo: ' + event.data);
    });

    server.addEventListener('close', (event) => {
      console.log('Client disconnected');
    });

    // Return the client WebSocket to the user
    return new Response(null, {
      status: 101,
      webSocket: client,
    });
  },
};

​
WebSocketPair

const pair = new WebSocketPair();
const [client, server] = Object.values(pair);

server.accept();
server.send('Hello from server');

client.addEventListener('message', (event) => {
  console.log(event.data); // "Hello from server"
});

Build docs developers (and LLMs) love

Get started for freeTalk to us