Presence history

Read current presence, historical presence events, and reconstructed snapshots through trusted proxy endpoints.

2 min read
View .mdEdit on GitHub

Presence answers two separate questions:

  • Who is subscribed now? Current presence is live channel state. The server pushes it to every member of a presence- channel over the WebSocket.
  • What membership transitions happened over time? Presence history is a durable, retained log of joins and leaves. Clients read it on demand over HTTP, through your backend.

The two are deliberately separate. Current membership keeps working even if the durable tier is unavailable, while history reads fail closed rather than return an incomplete log.

Current members

Subscribing to a presence- channel requires an auth response that includes channel_data with a server-derived user_id (see private and presence channels). Once subscribed, the client receives the full member list and then incremental changes:

lobby.ts
const channel = client.subscribe("presence-lobby");
channel.bind("sockudo:subscription_succeeded", (members) => {
console.log("online:", members.count, "me:", members.me);
members.each((member) => console.log(member.id, member.info));
});
channel.bind("sockudo:member_added", (member) => console.log("joined", member.id));
channel.bind("sockudo:member_removed", (member) => console.log("left", member.id));

Under the default Protocol V1 these events keep their Pusher names: pusher:subscription_succeeded, pusher:member_added, and pusher:member_removed.

How history reads work

Presence history is served by the signed Sockudo HTTP API, which requires the app secret. Client SDKs therefore never call it directly. They POST to a proxy endpoint on your backend, which checks the caller’s access and forwards a signed request.

Client SDK
Your backend
Sockudo HTTP API
1POST proxy { channel, params, action }
Authenticate session and authorize channel
2Signed GET presence/history or snapshot
3Page or snapshot JSON
4Same JSON
sequenceDiagram
  participant C as Client SDK
  participant B as Your backend
  participant S as Sockudo HTTP API
  C->>B: POST proxy { channel, params, action }
  Note over B: Authenticate session and authorize channel
  B->>S: Signed GET presence/history or snapshot
  S-->>B: Page or snapshot JSON
  B-->>C: Same JSON

The JavaScript SDK sends { channel, params, action: "history" } for history and { channel, params, action: "snapshot" } for snapshots.

Read history

Configure the proxy endpoint on the client, then call history() on a presence channel:

presence-history.ts
const client = new Sockudo("app-key", {
wsHost: "127.0.0.1",
wsPort: 6001,
forceTLS: false,
presenceHistory: {
endpoint: "/sockudo/presence-history",
headersProvider: () => ({ Authorization: `Bearer ${getSessionToken()}` }),
},
});
const channel = client.subscribe("presence-lobby");
let page = await channel.history({
limit: 50,
direction: "newest_first",
});
for (const item of page.items) {
console.log(item.serial, item.event, item.cause, item.user_id);
}
while (page.hasNext()) {
page = await page.next();
}
ParameterDescription
directionnewest_first or oldest_first.
limitPage size, bounded by the server’s max_page_size.
cursorOpaque cursor from a previous page. next() passes it for you.
start_serial, end_serialSerial bounds.
start_time_ms, end_time_msMillisecond time bounds. start and end are accepted aliases.

Each item carries stream_id, serial, published_at_ms, event (member_added or member_removed), cause, user_id, optional connection_id and dead_node_id, and the original presence_event. Causes include join, disconnect, timeout, forced_disconnect, and orphan_cleanup. Every page also returns continuity (retained range, complete, degraded, truncated_by_retention), so you can tell a short history from a truncated one.

Snapshot

A snapshot reconstructs effective membership at a point in the presence stream, by serial or by time:

snapshot.ts
const snapshot = await channel.snapshot({ at_serial: 42 });
// or: await channel.snapshot({ at_time_ms: Date.now() - 60_000 });
console.log(snapshot.member_count);
for (const member of snapshot.members) {
console.log(member.user_id, member.last_event, member.last_event_serial);
}

The response includes members, member_count, events_replayed, snapshot_serial, snapshot_time_ms, and continuity. at is accepted as an alias for at_time_ms.

Backend proxy

A minimal proxy with the Node.js server SDK. It forwards only the two supported actions, after confirming the caller may see the channel:

server/presence-history.ts
app.post("/sockudo/presence-history", express.json(), async (req, res) => {
const user = requireSessionUser(req);
const { channel, params = {}, action } = req.body;
if (!channel.startsWith("presence-") || !canAccessChannel(user, channel)) {
return res.status(403).end();
}
if (action === "history") {
return res.json(await sockudo.channelPresenceHistory(channel, params));
}
if (action === "snapshot") {
const response = await sockudo.get({
path: `/channels/${channel}/presence/history/snapshot`,
params,
});
return res.status(response.status).json(await response.json());
}
res.status(400).end();
});

The underlying routes are GET /apps/{appId}/channels/{channelName}/presence/history and GET /apps/{appId}/channels/{channelName}/presence/history/snapshot; see the HTTP endpoint reference.

Push relationship

Presence is about connected clients. Push registrations are about reachable devices. A user can be absent from a presence channel and still have a device eligible for push.

Use presence for live collaboration indicators. Use push channel subscriptions for offline notification eligibility.

Next steps