The Web Sockets API

W3C Working Draft 23 April 2009

This Version:
Latest Published Version:
Latest Editor's Draft:
Ian Hickson, Google, Inc.


This specification defines an API that enables Web pages to use the Web Sockets protocol for two-way communication with a remote host.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the most recently formally published revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives), whatwg@whatwg.org (subscribe, archives), or hybi@ietf.org (subscribe, archives). All feedback is welcome.

Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.

The latest stable version of the editor's draft of this specification is always available on the W3C CVS server. Change tracking for this document is available at the following location:

This specification is automatically generated from the corresponding section in the HTML5 specification's source document, as hosted in the WHATWG Subversion repository. Detailed change history for all of HTML5, including the parts that form this specification, can be found at the following locations:

The W3C Web Apps Working Group is the W3C working group responsible for this specification's progress along the W3C Recommendation track. This specification is the 23 April 2009 First Public Working Draft.

This specification is being developed in conjunction with an Internet Draft for a wire protocol, the Web Socket Protocol, available from the IETF at the following location:

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of contents

  1. 1 Introduction
  2. 2 Conformance requirements
    1. 2.1 Dependencies
  3. 3 Terminology
  4. 4 The WebSocket interface
  5. 5 Feedback from the protocol
    1. 5.1 Garbage collection
  6. References

1 Introduction

This section is non-normative.

To enable Web applications to maintain bidirectional communications with server-side processes, this specification introduces the WebSocket interface.

This interface does not allow for raw access to the underlying network. For example, this interface could not be used to implement an IRC client without proxying messages through a custom server.

An introduction to the client-side and server-side of using the direct connection APIs.

2 Conformance requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

The only conformance class defined by this specification is user agents.

User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

2.1 Dependencies

This specification relies on several other underlying specifications.


Many fundamental concepts from HTML5 are used by this specification. [HTML5]


The IDL blocks in this specification use the semantics of the WebIDL specification. [WebIDL]

3 Terminology

The construction "a Foo object", where Foo is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo".

The term DOM is used to refer to the API set made available to scripts in Web applications, and does not necessarily imply the existence of an actual Document object or of any other Node objects as defined in the DOM Core specifications. [DOM3CORE]

A DOM attribute is said to be getting when its value is being retrieved (e.g. by author script), and is said to be setting when a new value is assigned to it.

4 The WebSocket interface

[Constructor(in DOMString url)]
interface WebSocket {
  readonly attribute DOMString URL;

  // ready state
  const unsigned short CONNECTING = 0;
  const unsigned short OPEN = 1;
  const unsigned short CLOSED = 2;
  readonly attribute long readyState;

  // networking
           attribute Function onopen;
           attribute Function onmessage;
           attribute Function onclose;
  void postMessage(in DOMString data);
  void disconnect();

WebSocket objects must also implement the EventTarget interface. [DOM3EVENTS]

The WebSocket(url) constructor takes one argument, url, which specifies the URL to which to connect. When the WebSocket() constructor is invoked, the UA must run these steps:

  1. Parse the url argument.

  2. If the previous step failed, or if url does not have a <scheme> component whose value is either "ws" or "wss", when compared in an ASCII case-insensitive manner, then throw a SYNTAX_ERR exception.

  3. Return a new WebSocket object, and continue these steps in the background (without blocking scripts).

  4. Let origin be the ASCII serialization of the origin of the script that invoked the WebSocket() constructor, converted to lowercase.

  5. If the <scheme> component of url is "ws", set secure to false; otherwise, the <scheme> component is "wss", set secure to true.

  6. Let host be the value of the <host> component of url, converted to lowercase.

  7. If url has a <port> component, then let port be that component's value; otherwise, there is no explicit port.

  8. Let resource name be the value of the <path> component (which might be empty) of url.

  9. If resource name is the empty string, set it to a single character U+002F SOLIDUS (/).

  10. If url has a <query> component, then append a single U+003F QUESTION MARK (?) character to resource name, followed by the value of the <query> component.

  11. Establish a Web Socket connection to a host host, on port port (if one was specified), from origin, with the flag secure, and with resource name as the resource name.

The URL attribute must return the value that was passed to the constructor.

The readyState attribute represents the state of the connection. It can have the following values:

CONNECTING (numeric value 0)
The connection has not yet been established.
OPEN (numeric value 1)
The Web Socket connection is established and communication is possible.
CLOSED (numeric value 2)
The connection has been closed or could not be opened.

When the object is created its readyState must be set to CONNECTING (0). The steps executed when the constructor is invoked change this attribute's value.

The postMessage(data) method transmits data using the connection. If the connection is not established (readyState is not OPEN), it must raise an INVALID_STATE_ERR exception. If the connection is established, then the user agent must send data using the Web Socket.

The disconnect() method must close the Web Socket connection or connection attempt, if any. If the connection is already closed, it must do nothing. Closing the connection causes a close event to be fired and the readyState attribute's value to change, as described below.

The following are the event handler attributes that must be supported, as DOM attributes, by all objects implementing the WebSocket interface:
event handler attribute Event handler event type
onopen open
onmessage message
onclose close

5 Feedback from the protocol

When the Web Socket connection is established, the user agent must run the following steps:

  1. Change the readyState attribute's value to OPEN (1).

  2. Queue a task to fire a simple event named open at the WebSocket object.

When a Web Socket message has been received with text data, the user agent must create an event that uses the MessageEvent interface, with the event name message, which does not bubble, is cancelable, has no default action, and whose data attribute is set to data, and queue a task to dispatch it at the WebSocket object.

When the Web Socket connection is closed, the readyState attribute's value must be changed to CLOSED (2), and the user agent must queue a task to fire a simple event named close at the WebSocket object.

The task source for all tasks queued in this section is the Web Socket task source.

5.1 Garbage collection

A WebSocket object with an open connection must not be garbage collected if there are any event listeners registered for message events.

If a WebSocket object is garbage collected while its connection is still open, the user agent must close the Web Socket connection.


This section will be written in a future draft.