Realtime Servers & Channels

This page covers the current version of Realtime. For the original Workspace Settings–based channels, see Realtime (Legacy).

Realtime servers

A realtime server is what a client opens a websocket connection to. It’s the Realtime equivalent of an API group: a named container that holds channels, has its own settings, and — most importantly — has its own connection address, called its canonical. You can create as many realtime servers in a workspace as you need. Each one is independent:

Its own canonical, so clients connect to exactly the surface you intend
Its own channels and their access rules
Its own connect and disconnect triggers

That independence is what makes it safe to stand something new up next to an existing implementation. A legacy Realtime setup and a new realtime server use separate connection addresses, so both can run at once and neither is aware of the other.

Use separate servers to draw a hard line between audiences — for example, a public server for anonymous notification listeners and a second server for authenticated in-app collaboration. A client that connects to one can’t reach the other’s channels.

Finding Realtime in your workspace

Open the Realtime section

In the left side navigation of your workspace, click Realtime. The landing page is the Realtime Servers list.If you don’t see the entry, your role doesn’t have Read on the Workspace Realtime Features permission — the nav item isn’t rendered at all without it. See Access Control.

Create a server

Use New Server from the Realtime nav entry’s create dropdown, or the primary action on the server list.Canonicals may contain letters, numbers, dashes, and underscores; they must be unique, can’t be a reserved value, and can’t contain mvp-. Leave it blank when creating and Xano generates one for you.

Add channels and messages

Open a server and use Add Channel; open a channel and use Add Message. Every one of these panels has a XanoScript toggle that swaps the guided form for a script editor.

Finding the connection address

The canonical is shown in three places:

Where	What you see
Server list	Each server card shows its canonical top-right beside a link icon. The whole element is click-to-copy.
Server detail	Ellipsis menu → Security → the Canonical ID field, editable alongside the GUID.
Server settings	Displayed read-only as `Canonical: <value>` under the name field.

On the server detail page, each channel card’s link affordance copies a composed reference — <server-canonical>/<channel-path> — not the bare channel name. That pairing is what a client needs: the server canonical to connect, and the channel path to join.

In XanoScript

XanoScript

realtime_server "chat" {
  description = "Realtime server for chat"
  active = true
  history = "inherit"
  tags = ["chat"]
}

Only the name is required. canonical is also accepted as a clause — omit it when creating and the platform generates one.

After creating a server, pull its XanoScript and preserve the generated canonical on later pushes. In dev validation, pushing the same server again without its canonical regenerated the address, and clients using the previous address received Unknown connection hash. Keep the frontend connection URL aligned with the pulled canonical.

For a complete native WebSocket example, including the V2 URL and join acknowledgement, see Connecting a Client.

Channels

A channel is what a client joins once it’s connected. It’s the Realtime equivalent of an API route, and like a route it’s addressed by a path template:

Channel path template

rooms/{room_id}

A client joining rooms/42 matches this channel.

Path template rules

Letters, numbers, dashes, underscores, slashes, and {curly params}
Every {param} needs a matching typed entry in the channel’s input block. The builder enforces this and offers an Add missing button when a parameter has no declaration.
Names beginning with _ are reserved for platform lifecycle handlers.

Typed path parameters

Declare a type for each path parameter in the channel input schema:

Type	Declared value
`text`	Any string segment
`int`	A whole number
`decimal`	A number with a fractional part
`bool`	A boolean value

The schema declaration does not mean that every representation of the path parameter is already coerced to that type. In dev validation, both the join acknowledgement’s payload.params and realtime.get_session’s params contained {room_id: "42"} — a string — even though the channel declared int room_id.

Treat path values from acknowledgement and session objects as transport values. Validate or convert them before numeric comparisons or database use. Message payload validation is a separate boundary; see Messages.

Prefer a typed template over a catch-all. rooms/{room_id} with room_id declared as int tells you — and Xano — far more than a wildcard does, and identifies the parameter your join trigger must validate and authorize.

In XanoScript

A channel declares which server it belongs to by name. The path is unique only within its server.

XanoScript

channel "rooms/{room_id}" {
  realtime_server = "chat"
  description = "One chat room per room_id"
  access = {anonymous: false, presence: true}
  publish = {who: "authenticated", direct: false}
  conversation = {active: true, limit: 50, ttl: 86400}
  delivery = {guarantee: "at_least_once", per_recipient: true}
  rate_limit = {messages_per_minute: 60}
  history = "inherit"

  input {
    int room_id
  }

  tags = ["chat"]
}

realtime_server is the only required clause. Enable and disable a channel from the builder rather than in script.

Channel settings

Setting	Script key	Values
Anonymous clients	`access.anonymous`	boolean
Presence	`access.presence`	boolean
Who may publish	`publish.who`	`nobody` · `anyone` · `authenticated`
Client-to-client addressing	`publish.direct`	boolean
Rate limit	`rate_limit.messages_per_minute`	number (`0` = unlimited)
Transcript	`conversation.active`	boolean
Transcript size	`conversation.limit`	number
Transcript expiry	`conversation.ttl`	number (seconds)
Delivery guarantee	`delivery.guarantee`	`at_most_once` · `at_least_once`
Per-recipient tracking	`delivery.per_recipient`	boolean
Request history retention	`history`	`false` · `"inherit"` · `0` · `10` · `100` · `1000` · `10000` · `"all"`

What these mean for security is covered in Access Control.

Delivery guarantees

The guarantee is a channel setting — every delivery on the channel uses it. (Which clients receive a given message is chosen per message, with deliver_to.)

Guarantee	Behavior
`at_most_once`	Delivered zero or one time. Cheaper; a delivery can be lost.
`at_least_once`	Delivered one or more times. A recipient may see a duplicate, so client handlers should be idempotent.

delivery.per_recipient tracks delivery for each recipient individually rather than treating the publish as a single fire-and-forget event.

Match the guarantee to the channel’s traffic. A cursor position or a presence ping is fine at at_most_once — the next one is along shortly. Chat messages or order status changes usually want at_least_once.

Conversation transcript

A channel can keep a client-visible conversation transcript — recent messages available to a client that joins later. It’s bounded two ways:

Control	Purpose
`conversation.limit`	Maximum number of messages retained
`conversation.ttl`	How long a message stays in the transcript, in seconds

This is what makes “open the chat and see what was said before I got here” a channel setting rather than something you build from scratch. If you need durable history beyond the transcript window — a permanent record you can query, page through, and report on — write messages to a database table from the message’s function stack, exactly as you would in an API endpoint.

Build

Test & Deploy

Team Collaboration

Integrations

Security

Tutorials

Enterprise

Agencies

Account and Settings

Legal