Realtime (totalum-sdk/realtime)

import … from 'totalum-sdk/realtime' — or the same namespace on totalum from 'totalum-sdk'. Install, configuration and errors: Totalum SDK.

Live updates between the people using your app: chat, notifications, presence ("who is online"), collaborative editing, live dashboards and games. Your server mints a short-lived ticket for a room after its own auth check (ticket), the page opens the room's WebSocket with it (totalum-sdk/react), and your server can also publish to a room without a socket (publish). Billed in credits for each minute a room is awake and for each message, never per connection.

const { url } = await totalum.realtime.ticket({ room: 'chat:team-1', identity: { id: user.id, name: user.name } });

#totalumRealtime

totalumRealtime(options?: TotalumClientOptions): TotalumRealtime

Creates the realtime namespace (the same object as totalum.realtime, scope realtime), server side. The app's own server mints a short-lived ticket after its own auth check and hands {ticket, url} to the page; the page opens the wss:// url and never holds a key.

A room is billed in credits for each minute it is awake and for each message it receives, never per connection: a chat costs almost nothing, a busy game pays for its messages. A connection may send 120 messages a minute on the Free plan, 600 on Starter, 1,200 on Builder, 1,800 on Professional and 3,600 on Enterprise; the next one closes its socket with code 4429 (REALTIME_MESSAGE_RATE_EXCEEDED). Keep one room under about 1,000 messages a second in total: give each match or table its own room.

Parameters

Returns TotalumRealtime — The realtime namespace: the methods below.

Example

import { totalumRealtime } from 'totalum-sdk/realtime';

const realtime = totalumRealtime();
await realtime.publish('orders:shop-1', { event: 'order.created', data: { orderId: 'ord_42' } });

The namespace's type is exported as TotalumRealtime (import type { TotalumRealtime } from 'totalum-sdk/realtime').

#realtime.ticket

realtime.ticket(input: RealtimeTicketInput): Promise<RealtimeTicketOutput>

Mints a short-lived ticket that lets one browser join one room as one identity. Call it from your own route after your auth check (is this user allowed in this room?) and hand { url } to the page, which opens the WebSocket with it (useRealtimeChannel does this for you, from POST /api/realtime/ticket). By default the ticket only receives; pass permissions: { publish: true } to let the page send. The ticket must be used within ttl seconds (5–300, default 60); the socket then stays open. Minting is free. When the page opens the socket, the plan's live rooms and simultaneous connections are checked (the socket is refused with REALTIME_ROOM_LIMIT_REACHED or REALTIME_CONNECTION_LIMIT_REACHED).

Parameters

Returns Promise<RealtimeTicketOutput> — The ticket, the ready-to-open wss:// URL and what it grants.

Errors — besides the errors every call can throw:

Example

// src/app/api/realtime/ticket/route.ts
export async function POST(request: Request) {
  const user = await requireUser(); // your own session
  const { room } = (await request.json()) as { room: string };
  if (room !== `chat:${user.teamId}`) return new Response('Forbidden', { status: 403 });
  const ticket = await totalum.realtime.ticket({
    room,
    identity: { id: user.id, name: user.name },
    permissions: { publish: true },
  });
  return Response.json({ url: ticket.url });
}

Result:

{
  "ticket": "eyJ2IjoxLCJraWQiOiJrMjAyNnEzIiwicHJvamVjdElkIjoiYWNtZS1jcm0iLCJyb29tIjoiY2hhdDp0ZWFtLTEi…",
  "url": "wss://realtime.totalum.app/v1/rooms/chat:team-1?ticket=eyJ2IjoxLCJraWQiOiJrMjAyNnEz…",
  "room": "chat:team-1",
  "identity": { "id": "user_42", "name": "Ana" },
  "permissions": { "subscribe": true, "publish": true },
  "expiresAt": "2026-10-11T17:39:44.317Z"
}

#realtime.publish

realtime.publish(room: string, input: RealtimePublishInput): Promise<RealtimePublishOutput>

Publishes one message to every socket subscribed to room, from the app's own server (a route handler, a cron job): no socket needed. Subscribers receive the same message frame a socket publish sends, with event (default message) and identity (default { id: 'server' }). Resolves with the message id, its timestamp and the number of sockets it was sent to (0 when nobody is connected — it is not queued). Billed per message.

Parameters

Returns Promise<RealtimePublishOutput> — The message id, when it was sent, and how many sockets received it.

Errors — besides the errors every call can throw:

Example

const out = await totalum.realtime.publish('orders:shop-1', {
  event: 'order.created',
  data: { orderId: 'ord_42', total: 4900 },
});

Result:

{ "messageId": "d4d3ef78-9c21-4d15-a385-dc55af625cd3", "at": "2026-10-11T17:38:45.234Z", "connections": 3 }

#RealtimePublishInput

One message for realtime.publish().

#RealtimePublishOutput

The answer of realtime.publish().

#RealtimeTicketInput

The input of realtime.ticket().

#RealtimeTicketOutput

A ticket to join one room, from realtime.ticket().