Documentation

Getting started

An app is an isolated pub/sub namespace. Create one and three credentials appear immediately — there is no provisioning step and nothing to wait on.

From here: subscribe in the browser (next section), then publish from your backend with the trigger API. Both sides use the same app.

Connecting & subscribing

One script tag, hosted from Pulsely, bundles the SDK and its STOMP.js dependency together:

<script src="https://pulsely.dev/assets/js/pulsely.min.js"></script>

If you'd rather load STOMP.js and pulsely.js as two separate, unminified files — for reading the source, debugging, or serving from your own domain — that works too and always will. Either way, both StompJs and Pulsely land as globals.

const bp = new Pulsely( 'your-app-key' ); // safe in the browser
await bp.connect();

bp.subscribe( 'orders' );
bp.bind( 'created', ( data, meta ) => {
  console.log( 'new order:', data, meta.replayed );
} );

subscribe() can be called before or after connect() resolves — it queues either way. bind(eventName, callback) only fires for that exact event name; your callback receives (data, meta), where meta is { channel, event, replayed, fromClient }. If the channel's plan has message history on, subscribing replays recent messages (oldest → newest, meta.replayed === true) before the live stream starts, so a page that just loaded doesn't render empty.

To listen for everything without knowing event names ahead of time — a debug console, an activity log — use bindGlobal((data, meta) => …) instead; it fires alongside any bind() handlers, not in place of them.

Private & presence channels

Channels prefixed private- or presence- require your server to vouch for the connection. Two pieces: your backend mints a short-lived connection token, and your backend answers an authorization webhook when a subscribe comes in.

1. Mint a connection token

Every server SDK has the same authToken(userId, ttlSeconds) method:

const token = bp.authToken( user.id ); // "{expires}.{userId}.{hmac}"

token = bp.auth_token(user.id)

token = pulsely.authToken( user.id )

$token = $bp->authToken($user->id);

2. Present it from the browser

const bp = new Pulsely( 'your-app-key', { authToken: token } );
await bp.connect();
bp.subscribe( 'private-orders' );

3. Answer the auth webhook

Pulsely POSTs { channel_name, socket_id, user_token } to the endpoint registered on your channel rule, and honors {"authorized": true|false} back. Any timeout, non-200, or malformed response denies. authorizeChannel(…) builds the response shape for you:

app.post( '/pulsely/auth', ( req, res ) => {
  const user = userFromToken( req.body.user_token );
  res.json( bp.authorizeChannel( {
    authorized: canSee( user, req.body.channel_name ),
    userId: user.id,
    userInfo: { name: user.name }
  } ) );
} );

@app.route("/pulsely/auth", methods=["POST"])
def pulsely_auth():
    user = user_from_token(request.json["user_token"])
    return bp.authorize_channel(
        authorized=can_see(user, request.json["channel_name"]),
        user_id=user.id,
        user_info={"name": user.name},
    )

function answer( event, rc, prc ) {
  user = userFromToken( rc.user_token );
  return pulsely.authorizeChannel(
    authorized = canSee( user, rc.channel_name ),
    userId     = user.id,
    userInfo   = { "name" : user.name }
  );
}

$input = json_decode(file_get_contents('php://input'), true);
$user = userFromToken($input['user_token']);

echo json_encode($bp->authorizeChannel(
    canSee($user, $input['channel_name']),
    $user->id,
    ['name' => $user->name]
));

Presence channels

Subscribing to a presence- channel joins a live roster. The auth endpoint names the subscriber by returning user_id and optional user_info alongside authorized; membership is tracked per connection but reported per user — someone with three tabs open is one member, and only their first arrival and last departure produce an event.

bp.subscribe( 'presence-lobby' );

bp.bind( 'presence.subscription_succeeded', () => renderMembers( bp.members( 'presence-lobby' ) ) );
bp.bind( 'presence.member_added',   ( d ) => addMember( d.member ) );
bp.bind( 'presence.member_removed', ( d ) => removeMember( d.member ) );

bp.members( 'presence-lobby' );      // [{ user_id, user_info }, …]
bp.memberCount( 'presence-lobby' );  // distinct users

Presence requires a plan with allows_presence_channels and a matching rule in channel_auth_rules, the same as private channels.

Client-published events

By default only your server publishes, via the signed trigger API. Client events let browsers publish straight to each other — typing indicators, cursor positions, reactions — anywhere a round trip through your backend is wasted work. Because the app key is public, this is deliberately narrow:

bp.subscribe( 'private-chat-42' );
bp.trigger( 'private-chat-42', 'client-typing', { user: 'ada' } );

bp.bind( 'client-typing', ( data, meta ) => {
  // meta.fromClient === true — this came from a browser, not your server.
  showTypingIndicator( data.user );
} );

Client events are metered like any other message but are not written to history — they're ephemeral, and persisting them would let any connected browser write rows into your history table indefinitely. Senders never receive their own events back, and meta.fromClient tells your handler which messages came from a browser rather than your server — validate those. Toggle client events per app from the app page in the dashboard.

Watching the connection

Don't reach into bp.client — that's the underlying STOMP.js client, and touching it directly breaks the SDK's own bookkeeping (its callback properties hold one handler each, so setting your own silently replaces the SDK's). Use bp.connection.bind(…) instead:

bp.connection.bind( 'state_change', ( { previous, current, error } ) => {
  if ( current === 'connected' )    showBanner( 'Live' );
  if ( current === 'unavailable' )  showBanner( error || 'Reconnecting…' );
  if ( current === 'disconnected' ) showBanner( 'Disconnected' );
} );

States: initialized → connecting → connected / unavailable (dropped or refused — the SDK retries automatically) / disconnected (you called disconnect() — terminal, no retry). Call bp.disconnect() on page unload for prompt server-side cleanup rather than waiting for the broker to notice the socket died.

Publishing events (trigger API)

Your backend publishes with one signed HTTP call — no socket to hold open, no client library to keep alive:

POST /apps/{appId}/events
X-Pulsely-Timestamp: {epochSeconds}
X-Pulsely-Signature: {hex}
{"channel":"orders","event":"created","data":{...}}

Signed HMAC-SHA256 with your app secret, over four lines joined by real newlines: POST\n/apps/{appId}/events\n{timestamp}\n{sha256(body)}. The path and body hash are bound into the signature so a captured one can't be replayed against another app or payload; timestamps outside the auth window (600 seconds by default) are rejected. Every server SDK gets this right for you:

BODY='{"channel":"orders","event":"created","data":{"id":42}}'
TS=$(date +%s)
BODY_HASH=$(printf '%s' "$BODY" | shasum -a 256 | cut -d' ' -f1)
SIGNING=$(printf 'POST\n/apps/%s/events\n%s\n%s' "$APP_ID" "$TS" "$BODY_HASH")
SIG=$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$APP_SECRET" | sed 's/^.*= //')

curl -X POST "https://pulsely.dev/apps/$APP_ID/events" \
  -H "Content-Type: application/json" \
  -H "X-Pulsely-Timestamp: $TS" \
  -H "X-Pulsely-Signature: $SIG" \
  --data-binary "$BODY"

const bp = new Pulsely( { appId, appKey, appSecret, baseUrl } );
await bp.trigger( 'orders', 'created', { id: 42 } );

bp = Pulsely(app_id=app_id, app_key=app_key, app_secret=app_secret, base_url=base_url)
bp.trigger("orders", "created", {"id": 42})

pulsely = new Pulsely( appId = "…", appKey = "…", appSecret = "…" );
pulsely.trigger( "orders", "created", { "id" : 42 } );

$bp = new Pulsely(['appId' => $appId, 'appKey' => $appKey, 'appSecret' => $appSecret, 'baseUrl' => $baseUrl]);
$bp->trigger('orders', 'created', ['id' => 42]);

Non-2xx responses raise a typed error (PulselyError) carrying the status and parsed body, rather than returning silently. Responses: 200 ok, 400 malformed, 401 bad signature, 404 unknown/inactive app, 429 daily message limit reached.

Listing channels

Channels are ephemeral occupancy state, not persistent objects — this is the only way to find out what's currently live without maintaining your own shadow registry. Signed the same way as the trigger API, with an empty body.

Every occupied channel

TS=$(date +%s)
BODY_HASH=$(printf '%s' "" | shasum -a 256 | cut -d' ' -f1)
SIGNING=$(printf 'GET\n/apps/%s/channels\n%s\n%s' "$APP_ID" "$TS" "$BODY_HASH")
SIG=$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$APP_SECRET" | sed 's/^.*= //')

curl "https://pulsely.dev/apps/$APP_ID/channels?filter_by_prefix=presence-&info=user_count" \
  -H "X-Pulsely-Timestamp: $TS" \
  -H "X-Pulsely-Signature: $SIG"

const channels = await bp.listChannels( { filterByPrefix: 'presence-', info: 'user_count' } );
// { "presence-lobby": { user_count: 3 } }

channels = bp.list_channels(filter_by_prefix="presence-", info="user_count")
# {"presence-lobby": {"user_count": 3}}

channels = pulsely.listChannels( filterByPrefix = "presence-", info = "user_count" );

$channels = $bp->listChannels('presence-', 'user_count');

One channel's detail

# Same signing as above, path is /apps/{appId}/channels/{channelName}
curl "https://pulsely.dev/apps/$APP_ID/channels/orders" \
  -H "X-Pulsely-Timestamp: $TS" \
  -H "X-Pulsely-Signature: $SIG"
# {"occupied":true,"subscription_count":3}

const channel = await bp.getChannel( 'presence-lobby' );
// { occupied: true, subscription_count: 3, user_count: 2 }

channel = bp.get_channel("presence-lobby")
# {"occupied": True, "subscription_count": 3, "user_count": 2}

channel = pulsely.getChannel( "presence-lobby" );

$channel = $bp->getChannel('presence-lobby');

GET /apps/{appId}/channels returns every occupied channel as { channel_name: {} }; add ?filter_by_prefix= to scope by prefix, and ?info=user_count to include member counts inline for presence channels. Query params are never part of the signing string — only the route path is signed. GET /apps/{appId}/channels/{channelName} always returns 200, since "not occupied" is a normal state, not a missing resource. user_count (distinct presence members) only appears for presence- channels; subscription_count counts live connections, which can exceed user_count when one user has several tabs open.

Event webhooks

Your backend doesn't need to hold a socket open to react to what happens in a channel. Register an endpoint from the app page in the dashboard and Pulsely POSTs to it.

{
  "event": "channel_occupied",
  "data": { "channel": "orders" },
  "app_id": "a3f1…",
  "created_at": "2026-07-28T09:14:22"
}

Each request carries X-Pulsely-Timestamp and X-Pulsely-Signature, signed with your app secret using the same scheme as the trigger API — verify against the raw body, since a re-serialized object will not match.

app.post( '/pulsely/webhook', express.raw( { type: 'application/json' } ), ( req, res ) => {
  if ( !bp.verifyWebhook( req.body, req.headers ) ) return res.sendStatus( 401 );
  handle( JSON.parse( req.body ) );
  res.sendStatus( 200 );
} );

@app.route("/pulsely/webhook", methods=["POST"])
def pulsely_webhook():
    if not bp.verify_webhook(request.data, request.headers):
        return "", 401
    handle(request.get_json())
    return "", 200

Delivery is queued, never inline — a customer endpoint that hangs must not stall the broker thread that produced the event. Non-2xx responses retry with backoff (10s, 1m, 5m, 30m) up to five attempts, after which the row stops retrying but stays visible for debugging on the app page. Endpoints only receive the event types they subscribed to, and registering the same URL twice updates it rather than creating a duplicate.

Browser SDK reference

public/assets/js/pulsely.js — everything on the Pulsely client:

Events you'll bind to

The full task-by-task walkthrough this reference is drawn from lives in pulsely-js-guide.md at the root of the repo.

Server SDK reference

Thin, dependency-free clients — publish, mint tokens, answer auth requests, and (Node/Python) verify webhooks. Each is small enough to read in one sitting.

tests/sdk-check.mjs drives every verified SDK through a real publish, a rejected publish, a channel list/detail lookup, and a connection token that has to survive an actual STOMP CONNECT — and asserts all of them produce byte-identical signatures for a fixed payload, so a divergence in any one fails the build. The full breakdown, including the "why not roll your own" case for the four signing gotchas, lives in sdks/readme.md.

Administration

An account with admin access reaches /admin, which lists every account with its plan, app count, and usage today, and can change a plan, suspend or reactivate an account, and grant or revoke administrator access. Authorization is checked server-side on every action — re-read from the database each request, not trusted from the session — so revoking access takes effect immediately rather than at next login. Three guards stop an administrator locking everyone out: you cannot suspend yourself, you cannot revoke your own access, and the last remaining administrator cannot be demoted.