9 Communication

9.1 The MessageEvent interfaces

Messages in server-sent events, Web sockets, cross-document messaging, channel messaging, and broadcast channels use the MessageEvent interface for their message events:

[Constructor(DOMString type, optional MessageEventInit eventInitDict), Exposed=Window,Worker]
interface MessageEvent : Event {
  readonly attribute any data;
  readonly attribute DOMString origin;
  readonly attribute DOMString lastEventId;
  readonly attribute (WindowProxy or MessagePort)? source;
  readonly attribute MessagePort[]? ports;
};

dictionary MessageEventInit : EventInit {
  any data;
  DOMString origin;
  DOMString lastEventId;
  DOMString channel;
  (WindowProxy or MessagePort)? source;
  sequence<MessagePort> ports;
};
event . data

Returns the data of the message.

event . origin

Returns the origin of the message, for server-sent events and cross-document messaging.

event . lastEventId

Returns the last event ID string, for server-sent events.

event . source

Returns the WindowProxy of the source window, for cross-document messaging, and the MessagePort being attached, in the connect event fired at SharedWorkerGlobalScope objects.

event . ports

Returns the MessagePort array sent with the message, for cross-document messaging and channel messaging.

9.2 Server-sent events

9.2.1 Introduction

To enable servers to push data to Web pages over HTTP or using dedicated server-push protocols, this specification introduces the EventSource interface.

Using this API consists of creating an EventSource object and registering an event listener.

var source = new EventSource('updates.cgi');
source.onmessage = function (event) {
  alert(event.data);
};

On the server-side, the script ("updates.cgi" in this case) sends messages in the following form, with the text/event-stream MIME type:

data: This is the first message.

data: This is the second message, it
data: has two lines.

data: This is the third message.

Authors can separate events by using different event types. Here is a stream that has two event types, "add" and "remove":

event: add
data: 73857293

event: remove
data: 2153

event: add
data: 113411

The script to handle such a stream would look like this (where addHandler and removeHandler are functions that take one argument, the event):

var source = new EventSource('updates.cgi');
source.addEventListener('add', addHandler, false);
source.addEventListener('remove', removeHandler, false);

The default event type is "message".

Event streams are always decoded as UTF-8. There is no way to specify another character encoding.


Event stream requests can be redirected using HTTP 301 and 307 redirects as with normal HTTP requests. Clients will reconnect if the connection is closed; a client can be told to stop reconnecting using the HTTP 204 No Content response code.

Using this API rather than emulating it using XMLHttpRequest or an iframe allows the user agent to make better use of network resources in cases where the user agent implementor and the network operator are able to coordinate in advance. Amongst other benefits, this can result in significant savings in battery life on portable devices. This is discussed further in the section below on connectionless push.