Publish a Realtime event

POST

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

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

result = client.realtime.publish(
    "rap_01krdgeqcxet5s7t44vh8rt9mg",
    event="order.updated",
    channels=["orders", "presence-lobby"],
    data={"order_id": "ord_123", "status": "shipped"},
)
print(result.data)

result, err := client.Realtime.Publish(context.Background(), "rap_123", bird.RealtimePublishParams{
	Event:    "order.created",
	Channels: []string{"orders", "presence-lobby"},
	Data:     map[string]any{"order_id": "ord_1", "total": 4200},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(result.Data)

$result = $bird->realtime->publish($appId, (new RealtimePublish())
    ->setEvent('message.created')
    ->setChannels(['room-42'])
    ->setData(['text' => 'Hello, room!']));
echo count($result->getData() ?? []), ' channel(s)';

curl -X POST "https://us1.platform.bird.com/v1/realtime/apps/{realtime_app_id}/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order-updated",
    "channels": [
      "orders",
      "orders-42"
    ],
    "exclude_connection_id": "123.4567",
    "include": [
      "member_count"
    ]
  }'

响应200

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

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.

参数

realtime_app_id

string

ID of the Realtime app (rap_ prefix), as returned when the app was created.

请求载荷

event

string

必填

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

必填

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.

响应载荷

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

必填

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

Continue with the documentation, guides and examples for this topic. Resources are in English.

Explore the capabilityRealtime Follow the learning pathBuild your first integration Implementation guideSend your first realtime event

Try the practice and get an implementation brief

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

result = client.realtime.publish(
    "rap_01krdgeqcxet5s7t44vh8rt9mg",
    event="order.updated",
    channels=["orders", "presence-lobby"],
    data={"order_id": "ord_123", "status": "shipped"},
)
print(result.data)

result, err := client.Realtime.Publish(context.Background(), "rap_123", bird.RealtimePublishParams{
	Event:    "order.created",
	Channels: []string{"orders", "presence-lobby"},
	Data:     map[string]any{"order_id": "ord_1", "total": 4200},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(result.Data)

$result = $bird->realtime->publish($appId, (new RealtimePublish())
    ->setEvent('message.created')
    ->setChannels(['room-42'])
    ->setData(['text' => 'Hello, room!']));
echo count($result->getData() ?? []), ' channel(s)';

curl -X POST "https://us1.platform.bird.com/v1/realtime/apps/{realtime_app_id}/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order-updated",
    "channels": [
      "orders",
      "orders-42"
    ],
    "exclude_connection_id": "123.4567",
    "include": [
      "member_count"
    ]
  }'

响应200

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