---
title: "Publish a Realtime event"
canonical: "https://bird.com/docs/api/reference/publish-realtime-app-event"
---

# Publish a Realtime event

`POST /v1/realtime/apps/{realtime_app_id}/events`

Publishes an event to one or more channels of a Realtime app. Listing several channels broadcasts the event to all of them in one call. Connected clients subscribed to those channels receive it in real time.

## Code samples

**TypeScript**

```ts
const result = await bird.realtime.publish("rap_01krdgeqcxet5s7t44vh8rt9mg", {
  event: "order.updated",
  channels: ["orders", "presence-lobby"],
  data: { order_id: "ord_123", status: "shipped" },
});
console.log(result.data?.length); // one entry per channel
```

Examples: [TypeScript](/docs/api/reference/publish-realtime-app-event.ts.md) · [Python](/docs/api/reference/publish-realtime-app-event.py.md) · [Go](/docs/api/reference/publish-realtime-app-event.go.md) · [PHP](/docs/api/reference/publish-realtime-app-event.php.md) · [cURL](/docs/api/reference/publish-realtime-app-event.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "name": "orders-42"
    }
  ]
}
```

## Path parameters

- `realtime_app_id` (string): ID of the Realtime app (`rap_` prefix), as returned when the app was created.

## Request body

- `event` (string, required): The event name clients bind to. Application event names are free-form; the `bird:` and `bird_internal:` prefixes are reserved for the protocol and rejected.
- `channels` (array of string, required): The channels to deliver the event to (up to 100 per call). Prefix with `private-` or `presence-` for authenticated channels. A `private-encrypted-` channel must be the only channel in its publish: each encrypted channel has its own key, so a fan-out would hand the other channels unreadable ciphertext.
- `data`: Arbitrary JSON payload delivered as the event data: an object, array, or scalar. Cap: 10 KB serialized.
- `exclude_connection_id` (string): Exclude this connection from delivery, to avoid echoing a change back to the client that triggered it. The value is the client's connection id, assigned when its connection is established.
- `include` (array of string): Per-channel attributes to return alongside the publish, reflecting each channel's state at publish time. `member_count` is available only for presence channels. `connection_count` requires the app's connection-counting flag. Requesting attributes counts as one additional message toward usage.

## Response body

- `data` (array of object): Per-channel attributes at publish time, present only when the request asked for them via `include`; one item per distinct target channel, sorted by name.
- `data.member_count` (integer): Distinct members (presence channels only; requires `include=member_count`).
- `data.connection_count` (integer): Connections currently subscribed to this channel (requires `include=connection_count` and the app's connection-counting flag). Channel-scoped: distinct from the app-wide peak connections metric.
- `data.name` (string, required): A Realtime channel name. Only letters, digits, and _ - = @ , . ; Prefix with `private-` or `presence-` for authenticated channels, or `private-encrypted-` for channels whose payloads are end-to-end encrypted with a key only you hold.

## Related resources

- [Realtime](/realtime-api) (product)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first realtime event](/docs/get-started/send-your-first-realtime-event) (docs)

[Get an implementation brief](/learn/workspace?topic=realtime)