Channel rules

A channel rule applies to every channel whose name matches a pattern. It decides who can join, who can send, whether presence and history are on, and how much is allowed.

Realtime settings page — Realtime → Settings: Apps may publish, the default rule and rules for particular channels.

New channel rule sheet — Realtime → Channels → New channel rule.

Where

Services → Realtime → Channels (under Configure). The page is titled Channel rules: Governs who can subscribe or publish, and whether messages are kept. With no rules it says No channel rules yet. Click Add rule.

The fields

Field	Meaning
Pattern	Which channel names the rule covers. `*` is a wildcard. Placeholders insert facts about the caller: `org:{{ auth.org }}` matches only the channel for their organization, `user:{{ auth.id }}` only their own
Kind	What sort of channel it is (below)
Subscribe policy	Who may join, chosen in the rule picker. Placeholder: `authenticated`
Publish policy	Who may send
Presence	Track who is on the channel
History depth	How many recent messages to keep for latecomers
Retention (seconds)	For durable channels: how long a message is kept before it is purged
Message size limit (bytes)	Largest message
Publish rate limit (per second)	How often one sender may publish
Subscriber limit	The most people on one channel
Description	What this channel is for

Kinds

Kind	What it means
Public	Anyone who can subscribe sees it; no presence tracking unless turned on
Private	Scoped to the caller: a pattern like `user:{{ auth.id }}` that only that user can open
Presence	Tracks who is on the channel, in addition to messages
Protected	Subscribe is open, publish is restricted: a broadcast-only channel
Ephemeral	Nothing is kept for replay; a disconnected subscriber misses what happened while away
Durable	Every publish is written to the database, deduplicated by a client message id, and survives a restart

Rules are matched top to bottom

Matched top to bottom. The first rule whose pattern fits the channel name applies. Put specific patterns above general ones (chat:staff-* above chat:*). A channel that matches no rule uses the default rule (below).

Examples

Goal	Pattern	Kind	Subscribe	Publish
Public announcements from your server	`announce:*`	Protected	Signed-in users	Secret keys & Studio
Staff room	`ops:*`	Presence	Users with role `staff`	Users with role `staff`
A channel per organization	`org:{{ auth.org }}`	Presence	Signed-in users	Signed-in users
A private inbox per person	`user:{{ auth.id }}`	Private	Signed-in users	Secret keys & Studio
Chat rooms with history	`chat:*`	Presence, history 100	Signed-in users	Signed-in users
Orders feed that survives restarts	`orders:*`	Durable, retention 86400	Role `staff`	Secret keys & Studio

Because the placeholder {{ auth.id }} is filled with the caller’s own id, a person can open only their own inbox. No code is needed to enforce it.

Settings page

Services → Realtime → Settings is a simpler view of the same idea. Who may subscribe and publish. Applies to new connections within about 30 seconds.

Setting	Meaning
Who can listen	The default rule for subscribing
Who can publish	The default rule for sending
Apps may publish	Off: only your servers and flows publish; apps can still listen
Messages kept for latecomers	Default history depth
Show who is here	Default presence
Default rule	Used by any channel that matches none of the rules below.
Rules for particular channels	A list of Channel pattern rules, matched top to bottom; a pattern can use `` as a wildcard, and `{{ auth.org }}` for the user’s organization.* Remove rule deletes one

Use Settings for the defaults, and Channels when you need kinds, retention and limits.

When a rule takes effect

New rules and changes apply to new connections within about 30 seconds. A person already subscribed isn’t dropped; they hit the new rule on their next join.

What your app sees

subscribe() or send() throws a RealtimeError when a rule refuses. Test with the Playground and by acting as a person who should be refused; find the decision in Activity.

Rules on realtime

Rule recipes.

Playground

Test a rule.

Getting started

Set up in Studio

Use it from your app

Build well

Where

The fields

Kinds

Rules are matched top to bottom

Examples

Settings page

When a rule takes effect

What your app sees

Rules on realtime

Playground

​Where

​The fields

​Kinds

​Rules are matched top to bottom

​Examples

​Settings page

​When a rule takes effect

​What your app sees

Rules on realtime

Playground

Where

The fields

Kinds

Rules are matched top to bottom

Examples

Settings page

When a rule takes effect

What your app sees