<Intro>

<EndpointHeader />

<Description>

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.

</Description>

</Intro>

<Payload kind="request">

<Field name="event" type="string" required>

<Description>

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.

</Description>

</Field>

<Field name="channels" type="array of string" required>

<Description>

The channels to deliver the event to (up to 100 per call). Prefix with `private-` or `presence-` for authenticated channels.

</Description>

</Field>

<Field name="data">

<Description>

Arbitrary JSON payload delivered as the event data — an object, array, or scalar. Cap: 10 KB serialized.

</Description>

</Field>

<Field name="exclude_connection_id" type="string">

<Description>

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.

</Description>

</Field>

<Field name="include" type="array of string">

<Description>

Per-channel attributes to return alongside the publish, reflecting each channel's state at publish time (same semantics and validation errors as on the channel endpoints: `member_count` is presence-channels only, `connection_count` requires the app's connection-counting flag). Requesting attributes counts as one additional message toward usage.

</Description>

</Field>

</Payload>

<Payload kind="response">

<Field name="data" type="array of object">

<Description>

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.

</Description>

<FieldChildren kind="response">

<Field name="member_count" type="integer" prefix="data.">

<Description>

Distinct members (presence channels only; requires include=member_count).

</Description>

</Field>

<Field name="connection_count" type="integer" prefix="data.">

<Description>

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.

</Description>

</Field>

<Field name="name" type="string" prefix="data." required>

<Description>

A Realtime channel name. Only letters, digits, and _ - = @ , . ; Prefix with `private-` or `presence-` for authenticated channels.

</Description>

</Field>

</FieldChildren>

</Field>

</Payload>