Events veröffentlichen

Veröffentlichen Sie von Ihrem Server aus mit Ihrem Bird-API-Key sowie dem Key und Secret der Realtime-App. Liefern Sie das App-Secret niemals in Client-Code aus. Damit abonnierte Clients kurzlebige Signale austauschen können, verwenden Sie Client-Events auf Private- oder Presence-Channels.

Ein minimaler Publish

Ein Event benötigt einen Namen und mindestens einen Channel. Die optionale Payload kann ein beliebiges JSON-Objekt, -Array oder einen Skalar enthalten.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY,
  realtime: {
    key: process.env.BIRD_REALTIME_KEY,
    secret: process.env.BIRD_REALTIME_SECRET,
  },
});

await bird.realtime.publish("rap_01krdgeqcxet5s7t44vh8rt9mg", {
  event: "order-updated",
  channels: ["orders"],
  data: { id: 42, status: "shipped" },
});

import os

from bird import Bird

client = Bird(
    api_key=os.environ["BIRD_API_KEY"],
    realtime_key=os.environ["BIRD_REALTIME_KEY"],
    realtime_secret=os.environ["BIRD_REALTIME_SECRET"],
)

client.realtime.publish(
    "rap_01krdgeqcxet5s7t44vh8rt9mg",
    event="order-updated",
    channels=["orders"],
    data={"id": 42, "status": "shipped"},
)

client, err := bird.NewClient(
	option.WithAPIKey(os.Getenv("BIRD_API_KEY")),
	option.WithRealtimeCredentials(os.Getenv("BIRD_REALTIME_KEY"), os.Getenv("BIRD_REALTIME_SECRET")),
)
if err != nil {
	log.Fatal(err)
}

_, err = client.Realtime.Publish(context.Background(), "rap_01krdgeqcxet5s7t44vh8rt9mg", bird.RealtimePublishParams{
	Event:    "order-updated",
	Channels: []string{"orders"},
	Data:     map[string]any{"id": 42, "status": "shipped"},
})

use MessageBird\Bird;
use MessageBird\RealtimeOptions;
use MessageBird\Wire\Model\RealtimePublish;

$bird = new Bird(
    getenv('BIRD_API_KEY') ?: '',
    realtime: new RealtimeOptions(
        key: getenv('BIRD_REALTIME_KEY') ?: '',
        secret: getenv('BIRD_REALTIME_SECRET') ?: '',
    ),
);

$bird->realtime->publish('rap_01krdgeqcxet5s7t44vh8rt9mg', (new RealtimePublish())
    ->setEvent('order-updated')
    ->setChannels(['orders'])
    ->setData(['id' => 42, 'status' => 'shipped']));

curl -X POST https://us1.platform.bird.com/v1/realtime/apps/rap_01krdgeqcxet5s7t44vh8rt9mg/events \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
  -H "X-Realtime-Secret: $BIRD_REALTIME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order-updated",
    "channels": ["orders"],
    "data": { "id": 42, "status": "shipped" }
  }'

Clients, die an order-updated auf orders gebunden sind, empfangen das Event. Der API lehnt vom Server veröffentlichte Namen ab, die mit den Protokoll-Präfixen bird: oder bird_internal: beginnen. Vom Client ausgelöste Event-Namen müssen mit client- beginnen.

Die vollständige Anfrage und Antwort einschließlich aller Felder finden Sie in der Referenz Event veröffentlichen.

Was eine 200 bedeutet

Der Publish ist abgeschlossen, sobald die Realtime-Edge das Event angenommen hat. Die Zustellung erfolgt asynchron und liefert keine Empfangsbestätigung pro Client. Ein Client, der sich während der Zustellung trennt, kann das Event verpassen, und Realtime spielt es nach dem erneuten Verbinden nicht wieder ab.

Speichern Sie dauerhaften Zustand in Ihrer Datenbank. Verwenden Sie Events, um Änderungen anzukündigen, und lassen Sie Clients nach dem erneuten Verbinden den aktuellen Zustand neu laden.

An mehrere Channels senden

Ein Aufruf kann dasselbe Event an bis zu 100 Channels senden. Ein private-encrypted--Channel muss der einzige Channel in seinem Publish sein, da jeder verschlüsselte Channel einen anderen Key verwendet. Der API lehnt einen verschlüsselten Fan-out mit E23000 ab. Siehe Verschlüsselte Channels.

await bird.realtime.publish(appId, {
  event: "price-changed",
  channels: ["ticker-btc", "ticker-eth", "ticker-sol"],
  data: { at: "2026-07-31T09:00:00Z" },
});

client.realtime.publish(
    app_id,
    event="price-changed",
    channels=["ticker-btc", "ticker-eth", "ticker-sol"],
    data={"at": "2026-07-31T09:00:00Z"},
)

_, err := client.Realtime.Publish(context.Background(), appID, bird.RealtimePublishParams{
	Event:    "price-changed",
	Channels: []string{"ticker-btc", "ticker-eth", "ticker-sol"},
	Data:     map[string]any{"at": "2026-07-31T09:00:00Z"},
})

$bird->realtime->publish($appId, (new RealtimePublish())
    ->setEvent('price-changed')
    ->setChannels(['ticker-btc', 'ticker-eth', 'ticker-sol'])
    ->setData(['at' => '2026-07-31T09:00:00Z']));

curl -X POST "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/events" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
  -H "X-Realtime-Secret: $BIRD_REALTIME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "price-changed",
    "channels": ["ticker-btc", "ticker-eth", "ticker-sol"],
    "data": { "at": "2026-07-31T09:00:00Z" }
  }'

Jeder Ziel-Channel zählt als separate Nachricht für die Nutzung. Dieses Beispiel zählt als drei Nachrichten. Ein Publish an 10.000 benutzerspezifische Channels zählt demnach als 10.000 Nachrichten.

Unabhängige Events in einem Batch zusammenfassen

Ein Broadcast sendet ein Event an viele Channels. Ein Batch sendet bis zu 10 verschiedene Events, jeweils an einen Channel, in einer Anfrage.

await bird.realtime.publishBatch(appId, {
  events: [
    { event: "order-updated", channels: ["orders-42"], data: { status: "shipped" } },
    { event: "stock-changed", channels: ["inventory-99"], data: { left: 3 } },
  ],
});

client.realtime.publish_batch(
    app_id,
    events=[
        {"event": "order-updated", "channels": ["orders-42"], "data": {"status": "shipped"}},
        {"event": "stock-changed", "channels": ["inventory-99"], "data": {"left": 3}},
    ],
)

_, err := client.Realtime.PublishBatch(context.Background(), appID, bird.RealtimePublishBatchParams{
	Events: []bird.RealtimeBatchEventParams{
		{Event: "order-updated", Channel: "orders-42", Data: map[string]any{"status": "shipped"}},
		{Event: "stock-changed", Channel: "inventory-99", Data: map[string]any{"left": 3}},
	},
})

$bird->realtime->publishBatch($appId, (new RealtimeBatchPublish())
    ->setEvents([
        (new RealtimeBatchEvent())->setEvent('order-updated')->setChannel('orders-42')->setData(['status' => 'shipped']),
        (new RealtimeBatchEvent())->setEvent('stock-changed')->setChannel('inventory-99')->setData(['left' => 3]),
    ]));

curl -X POST "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/batch-events" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
  -H "X-Realtime-Secret: $BIRD_REALTIME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event": "order-updated", "channel": "orders-42", "data": { "status": "shipped" } },
      { "event": "stock-changed", "channel": "inventory-99", "data": { "left": 3 } }
    ]
  }'

Verwenden Sie einen Batch, um unabhängige Updates in einer Anfrage zusammenzufassen. Jedes Event zählt weiterhin einzeln für die Nutzung, und ein Batch akzeptiert maximal 10 Events. Siehe Batch veröffentlichen.

Den handelnden Client ausschließen

Wenn ein Client seine Aktion bereits lokal angewendet hat, übergeben Sie seine Connection-ID, um zu verhindern, dass der resultierende Publish dieselbe Änderung erneut anwendet. Die Edge überspringt nur diese Verbindung.

await bird.realtime.publish(appId, {
  event: "message.created",
  channels: ["presence-room-1"],
  data: { body: "hello" },
  exclude_connection_id: "26896.319537",
});

client.realtime.publish(
    app_id,
    event="message.created",
    channels=["presence-room-1"],
    data={"body": "hello"},
    exclude_connection_id="26896.319537",
)

_, err := client.Realtime.Publish(context.Background(), appID, bird.RealtimePublishParams{
	Event:               "message.created",
	Channels:            []string{"presence-room-1"},
	Data:                map[string]any{"body": "hello"},
	ExcludeConnectionID: "26896.319537",
})

$bird->realtime->publish($appId, (new RealtimePublish())
    ->setEvent('message.created')
    ->setChannels(['presence-room-1'])
    ->setData(['body' => 'hello'])
    ->setExcludeConnectionId('26896.319537'));

curl -X POST "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/events" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
  -H "X-Realtime-Secret: $BIRD_REALTIME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "message.created",
    "channels": ["presence-room-1"],
    "data": { "body": "hello" },
    "exclude_connection_id": "26896.319537"
  }'

Lesen Sie die ID aus der aktuellen Verbindung des Clients und fügen Sie sie in die Anfrage ein, die die Änderung auslöst. Andere Tabs verwenden eigene Verbindungen und empfangen das Event weiterhin.

Channel-Zustand beim Veröffentlichen lesen

Verwenden Sie include, um den Zustand jedes Ziel-Channels zum Zeitpunkt des Publishs zurückzugeben und eine separate Channel-State-Anfrage zu vermeiden:

const result = await bird.realtime.publish(appId, {
  event: "order-updated",
  channels: ["presence-lobby"],
  data: { id: 42 },
  include: ["member_count", "connection_count"],
});

result = client.realtime.publish(
    app_id,
    event="order-updated",
    channels=["presence-lobby"],
    data={"id": 42},
    include=["member_count", "connection_count"],
)

result, err := client.Realtime.Publish(context.Background(), appID, bird.RealtimePublishParams{
	Event:    "order-updated",
	Channels: []string{"presence-lobby"},
	Data:     map[string]any{"id": 42},
	Include:  []bird.RealtimeChannelInclude{bird.RealtimeIncludeMemberCount, bird.RealtimeIncludeConnectionCount},
})

$result = $bird->realtime->publish($appId, (new RealtimePublish())
    ->setEvent('order-updated')
    ->setChannels(['presence-lobby'])
    ->setData(['id' => 42])
    ->setInclude(['member_count', 'connection_count']));

curl -X POST "https://us1.platform.bird.com/v1/realtime/apps/$APP_ID/events" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
  -H "X-Realtime-Secret: $BIRD_REALTIME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order-updated",
    "channels": ["presence-lobby"],
    "data": { "id": 42 },
    "include": ["member_count", "connection_count"]
  }'

member_count funktioniert nur auf Presence-Channels. connection_count erfordert Connection-Counting in der App. Die Abfrage dieser Attribute zählt als eine zusätzliche Nachricht für die Nutzung.

Limits

Limit	Wert
Channels pro Publish	100
Events pro Batch	10
Event-Payload	10 KB serialisiert
Channel-Name	164 Zeichen, Buchstaben, Ziffern und _ - = @ , . ;
Event-Name	200 Zeichen

Das Überschreiten eines Limits gibt einen Validierungsfehler zurück. Der API kürzt die Anfrage nicht.

Sicheres erneutes Senden

Wiederholen Sie einen Publish mit demselben Idempotency-Key, um doppelte Zustellung zu vermeiden. Die TypeScript- und Go-SDKs erzeugen einen Key und verwenden ihn bei automatischen Retries wieder. Wenn Ihre Anwendung eine Anfrage wiederholt, liefern und verwenden Sie einen eigenen Key. Siehe Idempotenz.

Nächste Schritte

Channels autorisieren beschreibt, was ein private-- oder presence--Channel benötigt, bevor ein Client abonnieren kann.
Realtime-Übersicht erklärt Channels, Members und Connections und wo die Nutzung angezeigt wird.
Event-Empfänger ausschließen verhindert, dass der handelnde Client seine eigene Änderung empfängt.

Verwandte Ressourcen