Realtime — SDK & API

Realtime is wire-compatible with Pusher Channels. You keep the client and server libraries that you already use: the same subscribe / bind / trigger surface, the same channel model, and your existing auth endpoint. You only point them at ClutchCall. There is no new API to learn. On the client you have two first-class, drop-in options. Pick either one without changes to your channel or event code:

Stock pusher-js over WebSocket. Repoint wsHost and you are done. Use it when you want zero new dependencies and run on normal, reliable networks.
The ClutchCall QUIC-native realtime client. This is a pusher-js-API-compatible drop-in. It prefers WebTransport/QUIC and falls back automatically. Use it when mobile or lossy-network resilience matters (see When to pick which).

The server side is identical for both clients: the official Pusher server SDKs or the REST publish endpoint, the same channels, and the same HMAC auth.

This page is a reference for the compatible surface. If you already run Pusher, the only required change is the connection host (client) and the host option (server). App credentials come from the Realtime Console.

Connect a client

Construct a client with your app key. Point it at the ClutchCall realtime host. Choose one of the two clients below. After this step, the channel, bind, and connection-state code is identical for both clients.

Stock pusher-js (WebSocket)
ClutchCall QUIC-native client

Repoint stock pusher-js: set wsHost. Nothing else changes. This is the pure drop-in migration path.

npm install pusher-js

yarn add pusher-js

Browser (pusher-js)

import Pusher from "pusher-js";

const pusher = new Pusher("<APP_KEY>", {
  wsHost: "realtime.clutchcall.dev",
  forceTLS: true,          // wss:// — TLS on the wire
  // Auth for private-* / presence-* channels (see "Authorize channels"):
  channelAuthorization: {
    endpoint: "/pusher/auth",   // your backend route
    transport: "ajax",
  },
});

const channel = pusher.subscribe("public-updates");
channel.bind("price.changed", (data) => {
  console.log("new price", data);
});

string

required

The realtime host, realtime.clutchcall.dev. This is the one line that repoints stock pusher-js from Pusher’s cluster onto ClutchCall.

boolean

default:"false"

Set true to connect over wss://. Recommended for all production traffic.

number

Override only if you terminate on a non-default port. By default the client uses 443 under forceTLS.

Swap the import for the ClutchCall realtime subpath. The constructor is Pusher-compatible: same signature, same options, same returned client. It is a drop-in replacement for the pusher-js import. It prefers WebTransport/QUIC and falls back automatically down the transport ladder.

npm install @clutchcall/sdk

yarn add @clutchcall/sdk

Browser (QUIC-native, Pusher-compatible)

// Drop-in replacement for `import Pusher from "pusher-js"`:
import Pusher from "@clutchcall/sdk/realtime";

const pusher = new Pusher("<APP_KEY>", {
  wsHost: "realtime.clutchcall.dev",
  forceTLS: true,
  // Prefer QUIC, then degrade — see "Transport ladder" below:
  enabledTransports: ["webtransport", "ws", "sockjs"],
  channelAuthorization: {
    endpoint: "/pusher/auth",   // same backend route, unchanged
    transport: "ajax",
  },
});

// Identical channel/bind API — nothing below this line changes:
const channel = pusher.subscribe("public-updates");
channel.bind("price.changed", (data) => {
  console.log("new price", data);
});

string[]

default:"[\"webtransport\", \"ws\", \"sockjs\"]"

Ordered transport preference. The client tries each transport in turn and uses the first one that connects. Reorder or trim the list to force a transport (for example, ["ws"] disables QUIC completely).

The QUIC path connects to the same /app/<key> route over a WebTransport (HTTP/3) handler. The WebTransport server plane is live. On networks or proxies where WebTransport cannot establish, the client drops to WebSocket, then to SockJS. A blocked QUIC path does not cause a hard failure.

pusher-js (and the compatible client) addresses your app by key, not by app ID. The app ID is used only server-side. The client ignores the cluster option when you set wsHost explicitly. That is the correct configuration here.

string

Your backend route that signs private-* / presence-* subscriptions. It is identical for both clients. It is necessary only if you use private or presence channels.

Transport ladder

ClutchCall speaks the Pusher protocol. The QUIC-native client can carry it over three transports. The client negotiates them in order and degrades automatically:

Rung	Transport	How it connects	Wins when
1	WebTransport / QUIC	HTTP/3 to `/app/<key>`	Lossy, mobile, or high-latency links — no TCP head-of-line blocking, faster reconnects via 0-RTT resumption, survives network changes.
2	WebSocket	`wss://` to `/app/<key>`	Reliable wired networks, or where WebTransport is blocked. Identical to stock `pusher-js`.
3	SockJS	HTTP long-polling fallback	Restrictive proxies that break both of the above.

Browsers reach QUIC through WebTransport (HTTP/3). Native mobile apps can use raw QUIC directly and avoid the WebTransport framing layer. That is the native-SDK path.

Raw-QUIC on mobile ships through the native mobile SDKs, not the browser package. In the browser, “QUIC” always means WebTransport/HTTP-3. If you need the raw-QUIC mobile transport, check current availability for your platform in the Realtime Console before you depend on it.

When to pick which

Measure your own traffic. On a clean wired network, WebSocket-over-TCP is already fast, and stock pusher-js is the simplest option that works. The QUIC-native client helps on lossy, mobile, or high-latency networks, where TCP head-of-line blocking and slow reconnects hurt.

Situation	Recommended client
Pure drop-in migration off Pusher, no new deps	Stock `pusher-js` (WebSocket)
Desktop / server on reliable wired networks	Stock `pusher-js` (WebSocket)
Mobile web, flaky Wi-Fi, cellular, roaming	QUIC-native client
High packet loss or high RTT paths	QUIC-native client
Fast reconnect / connection migration matters	QUIC-native client

Both clients are drop-in. They share the same channel, event, presence, and auth code. You can start on stock pusher-js. If resilience needs grow, switch the import to @clutchcall/sdk/realtime later with no other changes.

// Public channel — open, no auth
const orders = pusher.subscribe("public-orders");

// Bind a handler for a single event…
orders.bind("order.created", (data) => render(data));

// …or catch every event on the channel
orders.bind_global((event, data) => console.log(event, data));

// Stop listening / leave
orders.unbind("order.created");
pusher.unsubscribe("public-orders");

Join a channel. The prefix decides the type. No prefix (or public-) is open. private- requires a signed subscription. presence- adds member state.

void

Leave a channel. This drops its binds and stops delivery.

Connection states

The client exposes the standard Pusher connection lifecycle. Bind to it to drive UI (for example, a “reconnecting” banner) or to gate publishes:

pusher.connection.bind("state_change", ({ previous, current }) => {
  console.log(`${previous} → ${current}`);
});

pusher.connection.bind("connected", () => {/* ready */});

State	Meaning
`initialized`	Client constructed, not yet connecting.
`connecting`	Opening the transport / handshaking.
`connected`	Live; subscriptions and events flow.
`unavailable`	Reachability lost; the client retries with backoff.
`failed`	Transport unsupported in this environment.
`disconnected`	Closed after `pusher.disconnect()`.

Authorize private & presence channels

private-* and presence-* subscriptions are HMAC-signed with your app secret. The browser never holds the secret. pusher-js POSTs the socket_id and channel name to your channelAuthorization.endpoint. Your backend signs the response with a Pusher server library. This is the standard Pusher auth flow. Reuse your existing endpoint unchanged.

Client requests authorization

On subscribe("private-…") or subscribe("presence-…"), pusher-js POSTs { socket_id, channel_name } to your auth endpoint.

Backend signs with the app secret

Your route constructs a Pusher server client with { appId, key, secret } and returns the signed auth payload. For presence channels you also attach the member’s user_id and user_info.

Client completes the subscribe

pusher-js forwards the signature to ClutchCall. ClutchCall checks the HMAC and admits the subscription.

Node (Express)
Python (Flask)

import Pusher from "pusher";
import express from "express";

const pusher = new Pusher({
  appId: "<APP_ID>",
  key: "<APP_KEY>",
  secret: "<APP_SECRET>",          // never shipped to the browser
  host: "realtime.clutchcall.dev",
  useTLS: true,
});

const app = express();
app.use(express.urlencoded({ extended: false }));

app.post("/pusher/auth", (req, res) => {
  const { socket_id, channel_name } = req.body;

  // Presence channel: identify the member
  if (channel_name.startsWith("presence-")) {
    const auth = pusher.authorizeChannel(socket_id, channel_name, {
      user_id: req.user.id,
      user_info: { name: req.user.name },
    });
    return res.send(auth);
  }

  // Private channel: signature only
  const auth = pusher.authorizeChannel(socket_id, channel_name);
  res.send(auth);
});

import pusher
from flask import Flask, request

client = pusher.Pusher(
    app_id="<APP_ID>",
    key="<APP_KEY>",
    secret="<APP_SECRET>",          # server-side only
    host="realtime.clutchcall.dev",
    ssl=True,
)

app = Flask(__name__)

@app.post("/pusher/auth")
def pusher_auth():
    socket_id = request.form["socket_id"]
    channel = request.form["channel_name"]

    if channel.startswith("presence-"):
        return client.authenticate(
            channel=channel,
            socket_id=socket_id,
            custom_data={
                "user_id": current_user.id,
                "user_info": {"name": current_user.name},
            },
        )
    return client.authenticate(channel=channel, socket_id=socket_id)

The app secret must stay only on your server. Any party with the secret can sign subscriptions and publish events. Create and rotate the secret in the Realtime Console.

Presence channels deliver pusher:subscription_succeeded with the current member list. They then deliver pusher:member_added / pusher:member_removed as members join and leave. These are the standard presence events. Bind them the usual way.

Publish from your server

Use the official Pusher server library, constructed with your { appId, key, secret, host }. Call trigger(channel, event, data). This fans the event out across the ClutchCall edge. Every subscriber on that channel receives it.

Node
Python
cURL (REST)

import Pusher from "pusher";

const pusher = new Pusher({
  appId: "<APP_ID>",
  key: "<APP_KEY>",
  secret: "<APP_SECRET>",
  host: "realtime.clutchcall.dev",
  useTLS: true,
});

await pusher.trigger("public-orders", "order.created", {
  id: "ord_123",
  total: 4200,
});

// Fan one event to several channels at once:
await pusher.trigger(
  ["public-orders", "private-ops"],
  "order.created",
  { id: "ord_123" },
);

import pusher

client = pusher.Pusher(
    app_id="<APP_ID>",
    key="<APP_KEY>",
    secret="<APP_SECRET>",
    host="realtime.clutchcall.dev",
    ssl=True,
)

client.trigger("public-orders", "order.created", {
    "id": "ord_123",
    "total": 4200,
})

# Publish over the REST API. The server libraries wrap this call and handle
# the request signing for you; this is the raw shape.
curl -X POST \
  "https://realtime.clutchcall.dev/apps/<APP_ID>/events" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "order.created",
        "channel": "public-orders",
        "data": "{\"id\":\"ord_123\"}"
      }'

Promise

Publish event with JSON data to one channel or an array of channels. data is delivered to every subscriber’s matching bind.

REST

The underlying publish endpoint on the realtime host. The body is { name, channel | channels, data }. Requests are HMAC-signed with the app secret (the server libraries do this for you). The Console Event Creator shows the exact cURL for any event that you compose.

The wire sends data as a JSON string. The Pusher server libraries serialize an object for you. Over raw REST, you pass a stringified body, as shown in the cURL tab.

Client events

On private-* and presence-* channels, subscribers can publish client-* events directly to each other (typing indicators, cursors). There is no round trip through your server. First enable client events for the app in the Console settings.

const channel = pusher.subscribe("presence-room-42");
channel.trigger("client-typing", { user: "ada" });

Client events must have the client- prefix. They are permitted only on authenticated (private-* / presence-*) channels. They are never delivered back to the sender.

Webhooks

Register endpoints in the Console to receive signed event batches. Batches are sent when channels become occupied or vacated, and when presence members join or leave. Check the X-Pusher-Signature HMAC (computed with the webhook signing secret) before you trust a payload.

Event	Fires when
`channel_occupied`	First subscriber joins a channel.
`channel_vacated`	Last subscriber leaves a channel.
`member_added`	A member joins a `presence-*` channel.
`member_removed`	A member leaves a `presence-*` channel.

Channel-existence and presence webhooks plus per-delivery HMAC signing are shipped. Some batching and additional webhook event groups (for example, client-event and cache webhooks) are still rolling out. Treat those as preview. Check availability for your deployment in the Console before you depend on them.

Compatibility scope

What is drop-in today

These features are drop-in today:

Public channels.
private-* HMAC subscription auth.
presence-* with member state.
client-* events.
subscribe/bind/unbind/unsubscribe.
The full connection-state lifecycle.
Server-side trigger (single and multi-channel) over both the server libraries and the REST publish endpoint.

Both clients speak this surface identically: stock pusher-js and the ClutchCall QUIC-native client (@clutchcall/sdk/realtime). The official Pusher server SDKs work when you change only the host.

Where to check before you rely on it

Some webhook batching and the broader webhook event set are still landing (see above). The browser QUIC path rides WebTransport (HTTP/3) and always has the WebSocket/SockJS fallback beneath it. Raw-QUIC on mobile ships through the native SDKs. Check availability for your platform before you depend on it. If you use an advanced or newer Pusher feature that is not listed under “drop-in”, check it against your deployment first.

Next steps

Realtime — Details

How channels, transports, and the edge fan-out fit together.

Realtime Console

Create app keys, publish test events, and configure webhooks.

Realtime — Cookbook

Copy-pasteable snippets: presence, private channels, server publish.

Realtime — Recipes

End-to-end builds: a live presence list and server-pushed notifications.

​Connect a client

​Transport ladder

​When to pick which

​Subscribe, bind, unsubscribe

​Connection states

​Authorize private & presence channels

​Publish from your server

​Client events

​Webhooks

​Compatibility scope

​Next steps

Realtime — Details

Realtime Console

Realtime — Cookbook

Realtime — Recipes

Connect a client

Transport ladder

When to pick which

Subscribe, bind, unsubscribe

Connection states

Authorize private & presence channels

Publish from your server

Client events

Webhooks

Compatibility scope

Next steps