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

# Publishing to a Channel from Xano

> realtime.publish injects a server-authored event onto a channel from any query, function, or task.

> [!NOTE]
>
> This page covers the current version of Realtime. For the legacy **Realtime Event** function, see [Realtime Functions (Legacy)](https://docs.xano.com/the-function-stack/functions/apis-and-lambdas/realtime-functions).

Not every realtime update starts with a client. Often the thing that changed is on the server: an order shipped, a background job finished, a nightly aggregation produced new numbers.

**`realtime.publish`** injects a server-authored event onto a channel from anywhere in Xano — a query, a custom function, or a scheduled task. The clients on that channel receive it over their existing connection, with no polling and no client-side request.

## Publish in the visual editor

In a function stack, add **Realtime Publish** from **APIs & Lambdas**, or search for it by name. It is the visual editor equivalent of `realtime.publish`.

| Panel field | XanoScript | What to enter |
| - | - | - |
| **Realtime Server** | `realtime_server` | Server name, such as `chat`; not its WebSocket canonical |
| **Channel** | `channel` | Resolved path, such as `rooms/42` |
| **Message** (optional) | `message` | Outgoing frame's `type`, such as `announcement` |
| **Data** | `data` | Payload delivered to subscribers |
| **Authentication → Database** (optional) | `auth_table` | Table used for identity attribution |
| **Authentication → Row ID** (optional) | `auth_id` | Attributed record ID; shown after selecting a database |

Realtime Server and Channel accept constants, variables, and expressions. Autocomplete offers workspace server names and channel templates as suggestions; it does not restrict values to that list. Resolve a template such as `rooms/{room_id}` to `rooms/42` before publishing. A channel path belongs to a particular server, so supply both fields. If suggestions fail to load, you can still enter the values directly.

**Message does not invoke a message handler.** Publishing with `message = "send"` delivers your Data as-is with `type: "send"`; it does not run the `send` handler's input validation, function stack, or per-message authentication. Authorize the calling API or stack before publishing. The optional Authentication fields attach identity metadata only; they do not validate credentials or grant access.

### Availability and version choice

**Realtime Publish** requires Realtime V2 support on the instance. In the picker category and search results, it is greyed out with an explanation when V2 is unavailable. An empty autocomplete list is a separate issue and does not mean V2 is disabled.

**Realtime Event (v1)** remains available for legacy connections. Its XanoScript statement is `api.realtime_event`. It cannot reach V2 subscribers and can complete without an error while delivering nothing to them. Do not substitute it when Realtime Publish is unavailable; check V2 availability on the instance instead.

## `realtime.publish`

| Argument | Required | Meaning |
| - | - | - |
| `realtime_server` | **Yes** | Target server, by name |
| `channel` | **Yes** | Target channel, as a **resolved path** — `"rooms/42"`, not the template `"rooms/{room_id}"` |
| `data` | **Yes** | The payload |
| `message` | No | Sets the delivered frame's `type`, which is what a client's receive handler discriminates on |
| `auth_table` | No | Asserted identity, for attribution |
| `auth_id` | No | Asserted identity, for attribution |
| `description` | No | Authoring annotation |
| `disabled` | No | Authoring annotation |

> [!WARNING]
>
> `auth_table` and `auth_id` are **attribution only**. They stamp an identity onto the event so recipients can see who it came from — they do **not** authenticate anything and are not an access-control mechanism. Enforce access with [channel settings and triggers](https://docs.xano.com/realtime/access-control.md).

`realtime.publish` returns nothing, so it takes no `as $variable` binding.

### Example

```java XanoScript lines icon="code" theme={null}
function "broadcast_announcement" {
  input {
    text body
  }

  stack {
    realtime.publish {
      realtime_server = "chat"
      channel = "rooms/42"
      message = "announcement"
      data = {body: $input.body}
    }
  }

  response = {ok: true}
}
```

## `realtime.get_session`

`realtime.get_session` reads the current realtime execution context; it is not needed to publish from an ordinary API or function. It takes no required arguments and requires an `as $variable` binding. See the [message handler example](https://docs.xano.com/realtime/connecting-a-client.md#create-an-echo-handler) for use inside a realtime message.

## Where you can publish from

| Source | Typical use |
| - | - |
| **API endpoint** | An action taken over REST fans out to everyone watching the affected resource |
| **Custom function** | Shared publish logic reused across several stacks |
| **Scheduled task** | A recurring job feeds a live dashboard |
| **Database trigger** | A table change pushes an update to subscribers of that record |

## Patterns

### Notification and dashboard channels

Set the channel's `publish.who` to `nobody`. Clients join and listen but can never send, and every update on the channel comes from a stack you control. This is the cleanest shape for notifications, status feeds, and live dashboards.

### Broadcast after a database write

Write the record first, then publish. Persisting before publishing means a client that joins after the fact — and reads the channel [transcript](https://docs.xano.com/realtime/realtime-servers-and-channels.md#conversation-transcript) or queries your table — sees the same thing as one that was connected the whole time.

### Progress and streaming

A long-running task can publish incremental updates on a channel keyed to the job, so the client sees progress rather than a spinner. The same pattern streams an LLM or agent response back over the connection as it's produced.

> [!TIP]
>
> Keep payloads small. Publishing an ID and a changed field, and letting the client fetch details when it needs them, keeps fan-out cheap — especially on a channel with many listeners or a [deliver trigger](https://docs.xano.com/realtime/realtime-triggers.md#channel-scope) that runs per recipient.

## Publishing vs. a message handler

Both put data on a channel, but they start from different places:

| | Message | `realtime.publish` |
| - | - | - |
| **Started by** | A connected client invoking a handler | Any Xano stack |
| **Has a payload schema** | Yes | No — you build the payload |
| **Delivery targeting** | Per-message `deliver_to` | The channel |
| **Appears in Request History** | Yes, under Messages | As part of the stack that published |

Use a message when the client is asking for something. Use `realtime.publish` when Xano has something to tell the client.

> [!NOTE]
>
> **`realtime.publish` is not `api.realtime_event`.** The Realtime Event function (`api.realtime_event`, shown as **Realtime Event (v1)** in the statement picker) belongs to [Realtime (Legacy)](https://docs.xano.com/realtime/realtime-in-xano). They are different statements targeting different systems — a legacy channel can't be reached with `realtime.publish`, and a v2 channel can't be reached with `api.realtime_event`.

## Verify delivery

Connect two V2 clients to the same server and resolved channel, and wait for both join acknowledgements. Run the publishing stack and confirm both receive an `action: "message"` frame with `type: "announcement"` and the supplied payload. A successful stack or HTTP response alone does not prove delivery. See [Connecting a Client](https://docs.xano.com/realtime/connecting-a-client.md).

## Next steps

> [card] [Messages](https://docs.xano.com/realtime/messages.md)
>
> Client-invoked handlers, and delivery targeting.

> [card] [Servers & Channels](https://docs.xano.com/realtime/realtime-servers-and-channels.md)
>
> Channel path templates, settings, and transcript.


## Related topics

- [Realtime Functions (Legacy)](https://docs.xano.com/the-function-stack/functions/apis-and-lambdas/realtime-functions.md)
- [Realtime](https://docs.xano.com/realtime/overview.md)
- [Update realtime channel details using XanoScript](https://docs.xano.com/api-reference/realtime/update-realtime-channel-details-using-xanoscript.md)


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