This page is Ready to Use

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

WebSocket Object API Details


Object for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.


Indicates the type of binary data being transmitted by the connection.
The number of bytes of data that have been queued using calls to send() but not yet transmitted to the network.
The extensions selected by the server.
An event listener to be called when the WebSocket connection’s readyState changes to CLOSED. Receives a CloseEvent named "close".
An event listener to be called when an error occurs. Receives an event named "error".
An event listener to be called when a message is received from the server. Receives a MessageEvent named "message".
An event listener to be called when the WebSocket connection’s readyState changes to OPEN. Receives an event named "open".
Indicates the name of the sub-protocol the server selected.
The current state of the connection, represented as a numeric constant.
The absolute URL as resolved by the constructor.


Closes the WebSocket connection or connection attempt, if any.
Transmits data to the server over the WebSocket connection.


No events.


The following function can be used to detect WebSocket support.

function webSocketSupported() {
  return "WebSocket" in window;

WebSockets are created via the WebSocket() constructor function.

WebSocket( url[, protocols] )

Complete example

if (window["WebSocket"]) {
        conn = new WebSocket("ws://localhost:12345/wsendpoint", "myProtocol");
        conn.onclose = function(evt) {
            console.log("Connection closed.");
        conn.onmessage = function(evt) {
    } else {
        console.log("Your browser does not support WebSockets");


 Use the WebSocket API to interface with the WebSocket protocol (RFC 6455). When you create a WebSocket connection, you upgrade the HTTP protocol to the WebSocket protocol during the initial handshake between the client and the server. You can use the WebSocket API to program your client to initiate the WebSocket handshake.

The first argument in the WebSocket constructor is the URL of the server to which you want to connect your client; the second argument is an optional argument where you can specify a subprotocol you want your client to use over WebSocket, when communicating with the server. The server must be WebSocket-enabled. When the client sends the WebSocket connection request to the server, the server acknowledges that it can speak WebSocket, and chooses the one (and only one) subprotocol to use on top of WebSocket. For example, a chat client might use XMPP over WebSocket, and therefore choose XMPP as the subprotocol.

When a WebSocket is constructed, it immediately attempts to connect to the given URL. There is no way to prevent or postpone the connection attempt. After construction, the WebSocket’s URL is accessible via its url property.


The WebSocket API specification defines two URI schemes, ws:// and wss://, foWebSocket Object r unencrypted and encrypted connections, respectively. For example, you could create a new WebSocket connection with the string "ws://". The URL specifies the host to connect to, the port, and (optionally) the protocols you want to use.

Note Secure connections (wss://) use WebSocket with TLS, and are recommended in most cases because they are more likely to work with proxy servers, which can buffer unencrypted traffic and close long-lived WebSocket connections without warning. WebSocket connections are bidirectional; communication can flow in either direction without specific requests and responses. Data can be text or binary.

To open a use a WebSocket connection, you must follow this procedure:

  • Create a WebSocket connection with a specific URL and one or more optional subprotocols, such as "chat". You can use the url property to see how the URL was parsed.
  • Determine the state of the connection with the readyState property. This state will change as the communication proceeds.
  • Check the type of data that will be sent using the binaryType, protocol, and extensions properties.
  • Set up event handlers for the connection. Event handlers include onopen, onmessage, onerror, and onclose. Use addEventListener to listen for events and removeEventListener when you no longer want to listen.
  • Send data to the host using the send method.
  • Determine the rate at which your data is moving with the bufferedAmount property.
  • Check to see whether data was sent to you.
  • Close the connection when you are finished with the close method.

Related specifications

W3C WebSocket Specification
W3C Candidate Recommendation

See also

External resources