Channels

A channel is a name. Everyone subscribed receives what is sent to it. Use a prefix and an id so one channel rule covers a group of them: chat:lobby, order:42, doc:abc. Who may join and send is decided by the rule you set in Studio (Services → Realtime → Channels). By default signed-in users may join and send.

const room = pawabase.realtime.channel("chat:lobby");

const stop = room.onEvent("message", (m) => {
  console.log(m.from, m.payload, m.sent_at);
});

await room.subscribe();
// later
stop();                      // stop this listener
await room.unsubscribe();    // leave the channel

room = pb.realtime.channel("chat:lobby")
room.on("message", lambda m: print(m["from"], m["payload"], m["sent_at"]))
await room.subscribe()
# later
await room.unsubscribe()

Asking for the same name twice returns the same channel, so parts of your app share one subscription. The first subscribe() opens the connection.

What a message holds

Field	Meaning
`id`	Unique. The client uses it to drop duplicates
`channel`	The channel name
`event`	The label it was sent with
`payload`	Whatever was sent: any JSON
`from`	The sender’s user id, or `"server"` for messages from your backend
`sent_at`	When it was accepted
`seq`	Order number, on messages read from history

Send

await room.send("message", { text: "hello" });
await room.send("typing", { on: true });

await room.send("message", {"text": "hello"})

It resolves with the message id once the server accepts it. You also receive your own messages, so render from what the channel delivers instead of adding yours twice. If the Publish policy refuses you (or Apps may publish is off), send throws RealtimeError. You can publish without subscribing (pawabase.realtime.publish(channel, event, payload)), which also works on the synchronous Python client.

Listen to one event or all

room.on("message", (m) => log(m.event, m.payload));      // every message
room.onEvent("typing", (m) => showTyping(m.from));        // only "typing"
room.on("subscribed", () => setStatus("live"));
room.on("closed", ({ reason }) => setStatus(reason));
room.on("error", (e) => report(e));

Python: room.on(None, handler) for every message; room.on("typing", handler) for one.

Read as a loop

for await (const message of room) render(message);

async for message in room:
    render(message)

The loop ends when you unsubscribe.

Typed payloads (TypeScript)

const room = pawabase.realtime.channel<{ text: string }, { name: string }>("chat:lobby");
room.onEvent("message", (m) => m.payload.text);     // string

In React

useEffect(() => {
  const room = pawabase.realtime.channel(`order:${orderId}`);
  const stop = room.onEvent("status", (m) => setStatus(m.payload.status));
  room.subscribe();
  return () => { stop(); room.unsubscribe(); };
}, [orderId]);

Naming channels

Do	Don’t
`order:42`, `doc:abc`, `chat:room-1`	Spaces or user-typed text
One prefix per kind of thing (so one rule covers it)	A different prefix per feature flag
Put the owner in the name when a rule needs it (`org:acme`)	Secrets in names

Errors

subscribe() and send() throw RealtimeError when a rule refuses: not signed in while the rule needs a user, wrong organization, the key is wrong. Check the rule in Studio, then Activity.

Presence

Who is here.

History

Messages for latecomers.

Getting started

Set up in Studio

Use it from your app

Build well

What a message holds

Send

Listen to one event or all

Read as a loop

Typed payloads (TypeScript)

In React

Naming channels

Errors

Presence

History

​Subscribe and listen

​What a message holds

​Send

​Listen to one event or all

​Read as a loop

​Typed payloads (TypeScript)

​In React

​Naming channels

​Errors

Presence

History

Subscribe and listen

What a message holds

Send

Listen to one event or all

Read as a loop

Typed payloads (TypeScript)

In React

Naming channels

Errors