Channel rules decide what happens to a message after it fans out. Each rule maps a channel name prefix to a message persistence policy, so chat: channels can keep 30 days of history while cursor: channels store nothing, without any per-message flags. Rules live in the dashboard under your app’s Channel rules tab.
The three policies
| Policy | What it does |
|---|---|
persist-all |
Every message is stored and readable through history, for the rule’s retention |
ephemeral |
Live-only. Messages are kept for about 2 minutes so reconnecting clients can heal gaps, then disappear |
retained-last |
Only the most recent message is kept, and it’s replayed to every client the moment it attaches |
persist-all rules also take a retention time, up to 30 days. Leave it unset to use your plan’s ceiling, per Limits.
Defaults
Without any rules of your own, an app behaves like this:
| Prefix | Policy |
|---|---|
chat: |
persist-all at the plan’s retention |
db:, dbsync: |
Reserved for Database Sync, rules on them are rejected |
| everything else | ephemeral |
So messages on an arbitrary channel are not stored by default. If clients need to read a channel’s backlog, put it under chat: or add a persist-all rule for its prefix.
Matching
The rule with the longest matching prefix wins. With rules for game: (ephemeral) and game:results: (persist-all), a message on game:results:42 is stored and a message on game:moves:42 is not. An empty prefix acts as the app-wide default and replaces the built-in ephemeral fallback. Rule changes propagate within about 15 seconds.
Retained last value
retained-last turns a channel into a last-value cache. Publish state to it whenever the state changes, and any client that attaches, including after a reconnect, immediately receives the current value without reading history:
const channel = realtime.channels.get('score:match42');
channel.subscribe((message) => {
render(message.data); // Fires right away with the latest value
});This fits state that only has a “now”, like scoreboards, sensor readings, or read receipts. No older messages accumulate, so history has nothing to return, and the publish response carries no serial.
Per-message ephemeral wins
A message published with { ephemeral: true } skips storage even on a persist-all channel. The flag is the per-message opt-out, the rule is the per-channel policy. There is no per-message opt-in the other way: a message on an ephemeral channel can’t ask to be stored.
Managing rules
Rules are created in the dashboard by an owner or admin. A rule’s prefix is fixed once created, so to move a rule you delete and recreate it. Each app can hold up to 64 rules. Since the policy decides what the platform keeps, check the matching rule before relying on history for a new channel family.