Skip to content
Workers
Visit Workers on GitHub
Set theme to dark (⇧+D)

WebSockets

Background

WebSockets allow you to communicate in real-time with your Cloudflare Workers serverless functions.

Constructor

// { 0: <WebSocket>, 1: <WebSocket> }let websocketPair = new WebSocketPair()

The WebSocketPair returned from this constructor is an Object, with two WebSockets at keys 0 and 1.

These WebSockets are commonly referred to as client and server. In the below example, we combine Object.values and ES6 destructuring to retrieve the WebSockets as client and server:

let [client, server] = Object.values(new WebSocketPair())

Methods

accept

  • accept()
    • Accepts the Websocket connection and begins terminating requests for the WebSocket at Cloudflare's edge. This effectively enables the Workers runtime to begin responding to and handling WebSocket requests.

addEventListener

  • addEventListener(eventWebSocketEvent, callbackFunctionFunction)
    • Add callback functions to be executed when an event has occurred on the WebSocket.

Parameters

  • event WebSocketEvent

    • The WebSocket event (see "Events" below) to listen to.
  • callbackFunction(messageMessage) Function- A function to be called when the Websocket responds to a specific event.

close

  • close(codenumber, reasonstring)

Close the WebSocket connection.

Parameters

  • codeinteger optional- An integer indicating the close code sent by the server. This should match an option from the list of status codes provided by the WebSocket spec.
  • reasonstring optional- A human-readable string indicating why the WebSocket connection was closed.

send

  • send(messagestring)

Send a message to the other WebSocket in this WebSocket pair.

Parameters

  • messagestring- The message to send down the WebSocket connection to the corresponding client. This should be a string or something coercible into a string; for instance, strings and numbers will be simply cast into strings, but objects and arrays should be cast to JSON strings using JSON.stringify, and parsed in the client.

Events

  • close

An event indicating the WebSocket has closed.

  • error

An event indicating there was an error with the WebSocket.

  • message

An event indicating a new message received from the client, including the data passed by the client.

Types

Message

  • data any - The data passed back from the other WebSocket in your pair.
  • type string - Defaults to message.

See also