---
title: "Getting Started"
description: "Install WordSocket, connect a site to WPSignal, and push the first realtime event to a browser."
url: https://wpsignal.io/docs/getting-started/
---

# Getting Started

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

## Prerequisites

-    WordPress 6.7 or later
-    PHP 8.2 or later
-    A free WPSignal account ([sign up at wpsignal.io](https://api.wpsignal.io/dashboard/signup))
-    Your WordPress site must be able to make outbound HTTP requests (most hosts allow this)

## Install the plugin

WordSocket is available on the [WordPress.org plugin directory](https://wordpress.org/plugins/wordsocket/). Install it from the WordPress admin or via WP-CLI:

```bash
wp plugin install wordsocket --activate
```

Or go to `WP Admin → Plugins → Add New` and search for **WordSocket**.

## Connect to WPSignal

### HTTPS

If you are using HTTPS, you can connect to the WPSignal server by clicking the **Connect to WPSignal** button on the WP Admin > WordSocket > Connection settings page.

### HTTP

If you are using HTTP, you can connect to the WPSignal server by entering your WPSignal API key from the [dashboard](https://api.wpsignal.io/dashboard/login) and clicking the **Connect to WPSignal** button on the WP Admin > WordSocket > Connection settings page.

## Verify with Explorer

Go to `WordSocket` in the WordPress admin menu and click the `Explorer` tab. This tab shows four panels:

-    **Registered Triggers**: table of all active triggers
-    **Live Event Log**: realtime stream of received events
-    **Publish Form**: manually send a test event
-    **Token Inspector**: decode and inspect your current JWT

If the connection status shows **Connected**, your setup is working. Use the Publish Form to send a test event and watch it appear in the Event Log instantly.

## Your first event in the browser

The plugin automatically enqueues `client.js` for logged-in users. The script connects via WebSocket (SSE fallback) and exposes `window.WPS`.

Listen for events with `WPS.on()`:

```js
WPS.on('post.updated', (data) => {
    console.log('Post updated:', data);
});
```

The built-in trigger fires `post.updated` whenever a post is saved. Enqueue your script with `'wpsignal'` as a dependency so `WPS` exists when it runs.

Every event is also dispatched on `document` as a native `CustomEvent` named `wpsignal:{event_name}`, if you prefer `addEventListener`; see the [JS API](https://wpsignal.io/docs/js-api/#dom-events).

Save any post in the WordPress editor and observe the event fire in your browser console.

## Custom triggers

Use the fluent `WPS::trigger()` builder to publish on any WordPress action hook.

New comment published

```php
add_action('wpsignal_loaded', function () {
    WPS::trigger('comment.created')
        ->on('wp_insert_comment', 10, 2)
        ->channel('events')
        ->data(fn ($comment_id, $comment) => [
            'comment_id' => $comment_id,
            'post_id'    => $comment->comment_post_ID,
            'author'     => $comment->comment_author,
        ])
        ->when(fn ($comment_id, $comment) => (int) $comment->comment_approved === 1)
        ->register();
});
```

WooCommerce order status change, inside a theme

```php
add_action('init', function () {
    WPS::trigger('order.status_changed')
        ->on('woocommerce_order_status_changed', 10, 3)
        ->channel('events')
        ->data(fn ($order_id, $old_status, $new_status) => [
            'order_id'   => $order_id,
            'old_status' => $old_status,
            'new_status' => $new_status,
        ])
        ->register();
});
```

## Direct publish

For one-off publishes outside of a hook, call `WPS::publish()` directly:

```php
WPS::publish('events', 'custom.event', [
    'message' => 'Hello from PHP',
    'time'    => time(),
]);
```

This sends an HMAC-signed HTTP POST to the WPSignal server immediately.

## Allowing public (logged-out) access

By default `client.js` is only enqueued for logged-in users. To serve realtime events to all visitors, one filter is all you need:

```php
add_filter('wpsignal_allow_client', '__return_true');
```

`wpsignal_allow_client` is the single access control for the realtime client. It gates the script enqueue and the connection token minted server-side at page load. Token refresh is handled automatically and protected by a WordPress REST nonce. No additional configuration required.

## Next steps

[

#### PHP API

WPS facade, trigger builder, and WordPress filters.

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

#### JS API

Subscribe, publish, and handle events from the browser.

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

#### Explorer

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

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