> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime Servers & Channels

> A realtime server is what a client connects to. A channel is what it joins.

> [!NOTE]
>
> This page covers the current version of Realtime. For the original Workspace Settings–based channels, see [Realtime (Legacy)](https://docs.xano.com/realtime/realtime-in-xano).

## 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.

> [!TIP]
>
> 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

**Step 1**

### 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](https://docs.xano.com/realtime/access-control.md#builder-permissions-rbac).

**Step 2**

### 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.

**Step 3**

### 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. |

> [!TIP]
>
> 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

```java XanoScript lines icon="code" theme={null}
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.

> [!WARNING]
>
> 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](https://docs.xano.com/realtime/connecting-a-client.md).

## 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**:

```text Channel path template theme={null}
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`.

> [!NOTE]
>
> 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](https://docs.xano.com/realtime/messages.md#payload-schema).

> [!TIP]
>
> 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.

```java XanoScript lines icon="code" theme={null}
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](https://docs.xano.com/realtime/access-control.md).

## 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`](https://docs.xano.com/realtime/messages#delivery).)

| 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.

> [!NOTE]
>
> 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.

## Next steps

> [card] [Messages](https://docs.xano.com/realtime/messages.md)
>
> Define the handlers clients invoke on a channel.

> [card] [Access Control](https://docs.xano.com/realtime/access-control.md)
>
> Decide who can connect, join, publish, and receive.


## Related topics

- [Realtime Messages](https://docs.xano.com/realtime/messages.md)
- [Realtime Triggers](https://docs.xano.com/realtime/realtime-triggers.md)
- [Realtime Access Control](https://docs.xano.com/realtime/access-control.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.