A realtime chat

You’ll build chat rooms: people open a room, see the recent conversation, watch new messages arrive live, see who else is there, and see when someone is typing. Rooms are private to their members. You’ll use: Realtime channels, presence, history, channel rules. Before you start: have sign-in working, as in An app with signed-in users.

How it works

A channel is a name, like room:design. Everyone subscribed receives what’s sent to it. A channel rule matches a pattern of names (room:*) and decides who may join and send, whether presence is tracked, and how many messages are kept for latecomers.

Need	Realtime feature
Messages arriving live	`subscribe()` and `onEvent("message")`
The conversation so far	History depth on the rule, and `history(50)`
Who’s here	Presence on the rule, and `presenceState()`
”Ada is typing…”	A light `typing` message, not stored

Channel history is a backlog for context. With the rule’s Kind set to Durable, kept messages also survive a restart, for the rule’s Retention. It still isn’t a searchable archive. If messages must be kept forever (searchable, exportable), also save them to a table; see Variation: permanent messages.

1. Create the channel rule

Realtime → Channels → New channel rule:

Field	Value
Pattern	`room:*`
Subscribe policy	Signed-in users (tighten in step 6)
Publish policy	Signed-in users
Presence	on
History depth	`50`
Message size limit (bytes)	`4000`
Publish rate limit (per second)	`5`

2. Open a room

src/room.ts

import { pawabase } from "./pawabase";

type ChatMessage = { text: string; name: string };

export async function openRoom(id: string, me: { name: string }, render: (m: any) => void) {
  const room = pawabase.realtime.channel<ChatMessage>(`room:${id}`, { presence: { name: me.name } });
  const seen = new Set<string>();
  const show = (m: any) => { if (!seen.has(m.id)) { seen.add(m.id); render(m); } };

  room.onEvent("message", show);            // listen before subscribing, so nothing is missed
  await room.subscribe();

  for (const m of await room.history(50)) show(m);   // oldest first; the Set drops anything already shown
  return room;
}

Asking for the same channel name twice returns the same channel object, so separate components share one subscription.

3. Send messages

import { RateLimitError, RealtimeError } from "@pawabase/client";

export async function send(room: any, text: string, me: { name: string }) {
  try {
    await room.send("message", { text, name: me.name });
  } catch (e) {
    if (e instanceof RateLimitError) return "slow down";
    if (e instanceof RealtimeError) return "you can't post here";
    throw e;
  }
}

Each message arrives as { id, channel, event, payload, from, sent_at }. from is the sender’s user id (or "server" for your backend), filled in by Pawabase, so it can’t be faked. Show payload.name, but trust from.

4. Who’s online

room.on("presence", ({ members }) => {
  const people = new Map(members.map((m) => [m.user_id, m.meta.name]));   // one entry per person
  renderOnline([...people.values()]);
});

One person on two devices appears twice in members, with different presence_refs; group by user_id. Entries disappear when someone leaves or their connection drops.

5. Typing indicators

Typing is frequent and disposable, so send it as a message instead of presence, and don’t keep it:

let last = 0;
input.addEventListener("input", () => {
  if (Date.now() - last > 2000) { last = Date.now(); room.send("typing", {}); }
});
room.onEvent("typing", (m) => showTyping(m.from));

Throttling to one every two seconds stays well under the rule’s publish rate limit.

6. Make rooms private to their members

Keep a room_members table (room_id, user_id) and check membership in the rule. Channel rules read the caller and the channel name, not other tables, so give each member the channel through their token, or put the members in the channel’s name. The simplest secure pattern uses the person’s id in the channel name for direct messages, and an organization for team rooms:

Room type	Pattern	Subscribe and publish policy
A company’s rooms	`org:{{ auth.org }}:room:*`	Signed-in users (the pattern already pins the organization)
A person’s inbox	`inbox:{{ auth.user_id }}`	Signed-in users

A placeholder like {{ auth.org }} counts as a wildcard when deciding which rule governs a channel, and must equal the caller’s own value to let them in: someone at Globex asking for org:acme:room:design is governed by this rule and refused, rather than falling through to a looser default. See Channel rules and Rules on realtime. For rooms whose members are a list you manage yourself, publish messages from a flow that checks membership, and let clients only subscribe.

Variation: permanent messages

To keep every message, write it to a messages table, and let the table broadcast it:

Create messages (room_id, author_id as Owner field, text) with suitable rules.
Turn on Broadcast changes in the table’s settings.
Send with pawabase.from("messages").create({ room_id, text }), and listen with record changes.

Now history is a normal query with paging and search, and the record rules decide who sees what.

Test it

Open two browsers signed in as different people, join the same room, and check: messages appear in both, the online list shows both, typing shows on the other side, and reloading shows the last messages. In Activity → Realtime, watch policy errors while you try a room you shouldn’t reach.

Troubleshooting

Problem	Cause	Fix
Subscribing fails	No rule matches the name, or the subscribe policy refuses	Check the pattern and policy; see Activity → Realtime → Policy errors
No history	History depth is 0	Set it on the rule
Presence is empty	Presence is off on the rule	Turn it on
Messages appear twice	History and live overlap	De-duplicate by `id`, as in step 2
`RateLimitError` when typing	Typing sent on every keystroke	Throttle it

Channels

The full channel API.

Channel rules

Patterns, kinds and limits.

Welcome

Concepts

Quickstarts

Tutorials

How it works

1. Create the channel rule

2. Open a room

3. Send messages

4. Who’s online

5. Typing indicators

6. Make rooms private to their members

Variation: permanent messages

Test it

Troubleshooting

Channels

Channel rules

​How it works

​1. Create the channel rule

​2. Open a room

​3. Send messages

​4. Who’s online

​5. Typing indicators

​6. Make rooms private to their members

​Variation: permanent messages

​Test it

​Troubleshooting

Channels

Channel rules

How it works

1. Create the channel rule

2. Open a room

3. Send messages

4. Who’s online

5. Typing indicators

6. Make rooms private to their members

Variation: permanent messages

Test it

Troubleshooting