---
title: "JS API Reference"
description: "The window.WPS browser client: subscribe, publish, presence, handler types, connection state, and DOM events."
url: https://wpsignal.io/docs/js-api/
---

# JS API: window.WPS

The plugin exposes `window.WPS` on all pages where the client script is loaded.

If you are building a WordPress block or script with a build tool, add `'wpsignal'` as a dependency in your `wp_enqueue_script` call to ensure WPS loads first.

### WPS.subscribe( channels )

Subscribe to additional channels on the shared connection.

| Parameter | Type |
| --- | --- |
| channels | string\[\] |

### WPS.unsubscribe( channels )

Unsubscribe from channels.

| Parameter | Type |
| --- | --- |
| channels | string\[\] |

### WPS.publish( channel, event, data? )

Publish a JSON message through the WebSocket. No-ops on SSE (one-way transport).

| Parameter | Type |
| --- | --- |
| channel | string |
| event | string |
| data? | Record< string, unknown > |

### WPS.publishBinary( channel, data )

Send a raw binary frame to the server over the WebSocket. Frame format: 2-byte BE channel name length + channel bytes + payload. No-ops on SSE (one-way transport) or when not connected.

| Parameter | Type |
| --- | --- |
| channel | string |
| data | Uint8Array |

### WPS.setPresence( channel, state )

Enter or update connection-scoped presence on a channel. The relay drops the membership the instant this socket closes, and the client re-sends it on reconnect; pass null to leave, which is announced at once. Subscribers of the channel receive \`wps.presence\` join/leave/sync events (\`channel\` is the site-relative name, \`woo:carts:live\`). Requires WebSocket; no-op on SSE.

| Parameter | Type |
| --- | --- |
| channel | string |
| state | Record< string, unknown > \| null |

### WPS.on( event, handler )

`() => void`

Register a handler for a specific event name. Returns unsubscribe fn.

| Parameter | Type |
| --- | --- |
| event | string |
| handler | WPSEventHandler |

### WPS.onMessage( handler )

`() => void`

Register a catch-all handler for incoming JSON messages. Returns unsubscribe fn.

| Parameter | Type |
| --- | --- |
| handler | WPSMessageHandler |

### WPS.onBinaryMessage( handler )

`() => void`

Register a handler for incoming binary frames. Returns unsubscribe fn.

| Parameter | Type |
| --- | --- |
| handler | WPSBinaryHandler |

### WPS.connected

readonly property `boolean`

Whether the connection is currently open.

### WPS.transport

readonly property `WPSTransportName | null`

Current transport layer, or null while still connecting.

### WPS.status

readonly property `WPSStatus`

Current transport state and capabilities.

### WPS.onConnectionChange( handler )

`() => void`

Register a callback for connection state changes. Returns unsubscribe fn.

| Parameter | Type |
| --- | --- |
| handler | ( connected: boolean ) => void |

### WPS.onStateChange( handler )

`() => void`

Register a callback receiving the full connection state (error, retry countdown, failure count). Returns unsubscribe fn.

| Parameter | Type |
| --- | --- |
| handler | ( state: WPSConnectionState ) => void |

### WPS.state

readonly property `WPSConnectionState`

The current connection state, as delivered to onStateChange.

### WPS.uuid( )

`string`

A version-4 UUID. Works on plain HTTP pages too, where \`crypto.randomUUID\` does not exist (it needs a secure context); use it instead of calling \`crypto.randomUUID()\` directly. Needs no connection.

### WPS.visitorId( )

`string`

This browser's stable id, kept in localStorage and shared by every tab and every extension on the site, for counting people rather than sockets (pass it in presence state). It names a browser, not a person; when storage is blocked it lasts for the page load only.

### WPS.onChannel( channel, expected )

`boolean`

Whether an event's \`channel\` is the \`expected\` one, given by its site-relative name (\`woo:stock\`); the qualified \`site:{id}:woo:stock\` matches too. Any tokened browser may publish on a public channel, so check this in a handler before trusting the event's data.

| Parameter | Type |
| --- | --- |
| channel | string |
| expected | string |

## Handler types

These types are used as parameters in the methods above.

## Connection state

The shapes handed to `WPS.onStateChange()` and returned by `WPS.state`. `WPSConnectionErrorCode` mirrors `@wordpress/sync`, so the block editor can pick its own copy for each case without translating anything.

## DOM CustomEvents

For every received message the client also dispatches a `CustomEvent` on `document`. The event name is `wpsignal:{event}`. Use these when you prefer the standard DOM event model, or when your script may run before the client has loaded: `WPS.on()` is the shorter form everywhere else.

```js
document.addEventListener('wpsignal:post.updated', (e) => {
    // e.data is the payload, e.channel the channel it arrived on
    // (both also under e.detail, as { channel, data }).
    console.log(e.channel, e.data);
});
```

## Next steps

[

#### Getting Started

From a fresh WordPress install to live browser events in under 5 minutes.

](https://wpsignal.io/docs/getting-started/)[

#### PHP API

WPS facade, trigger builder, and WordPress filters.

](https://wpsignal.io/docs/php-api/)[

#### Explorer

Interactive playground: connect, publish, and inspect events live.

](https://wpsignal.io/docs/explorer/)