Menerbitkan event

Terbitkan dari server Anda menggunakan kunci Bird API serta key dan secret aplikasi Realtime. Jangan pernah menyertakan app secret dalam kode klien. Untuk membiarkan klien yang berlangganan bertukar sinyal singkat, gunakan client event di channel private atau presence.

Publish minimal

Sebuah event memerlukan nama dan setidaknya satu channel. Payload opsionalnya dapat berisi objek, array, atau skalar JSON apa pun.

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" }
  }'

Klien yang terikat ke order-updated di orders menerima event tersebut. API menolak nama yang diterbitkan server jika diawali dengan prefiks protokol bird: atau bird_internal:. Nama event yang berasal dari klien harus diawali dengan client-.

Request dan response lengkap, termasuk setiap field, ada di referensi publish an event.

Arti respons 200

Publish selesai setelah edge Realtime menerima event. Pengiriman bersifat asinkron dan tidak ada konfirmasi per klien. Klien yang terputus saat pengiriman dapat melewatkan event, dan Realtime tidak memutar ulang event setelah koneksi ulang.

Simpan state yang tahan lama di database Anda. Gunakan event untuk mengumumkan perubahan, lalu minta klien memuat ulang state terkini setelah koneksi ulang.

Broadcast ke beberapa channel

Satu panggilan dapat mengirim event yang sama ke maksimal 100 channel. Channel private-encrypted- harus menjadi satu-satunya channel dalam publish-nya karena setiap channel terenkripsi menggunakan kunci berbeda. API menolak fan-out terenkripsi dengan E23000. Lihat Channel terenkripsi.

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" }
  }'

Setiap channel target dihitung sebagai satu pesan terpisah untuk penggunaan. Contoh ini dihitung sebagai tiga pesan. Publish ke 10.000 channel per pengguna dihitung sebagai 10.000 pesan.

Batch event yang tidak terkait

Broadcast mengirim satu event ke banyak channel. Batch mengirim hingga 10 event berbeda, masing-masing ke satu channel, dalam satu request.

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 } }
    ]
  }'

Gunakan batch untuk menggabungkan pembaruan yang tidak terkait ke dalam satu request. Setiap event tetap dihitung terpisah untuk penggunaan, dan satu batch menerima maksimal 10 event. Lihat Publish a batch.

Mengecualikan klien yang melakukan aksi

Jika klien sudah menerapkan aksinya secara lokal, kirimkan connection ID-nya untuk mencegah publish yang dihasilkan menerapkan perubahan yang sama lagi. Edge hanya melewati koneksi tersebut.

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"
  }'

Baca ID dari koneksi klien saat ini dan sertakan dalam request yang memicu perubahan. Tab lain menggunakan koneksi terpisah dan tetap menerima event.

Membaca state channel saat publish

Gunakan include untuk mengembalikan state setiap channel target pada saat publish dan menghindari request channel-state terpisah:

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 hanya berfungsi di channel presence. connection_count memerlukan penghitungan koneksi pada aplikasi. Meminta atribut ini dihitung sebagai satu pesan tambahan untuk penggunaan.

Batas

Batas	Nilai
Channel per publish	100
Event per batch	10
Payload event	10 KB serial
Nama channel	164 karakter, huruf, angka, dan _ - = @ , . ;
Nama event	200 karakter

Melebihi batas mana pun menghasilkan error validasi. API tidak memotong request.

Coba lagi dengan aman

Coba lagi publish dengan Idempotency-Key yang sama untuk menghindari pengiriman duplikat. SDK TypeScript dan Go menghasilkan kunci dan menggunakannya kembali untuk percobaan ulang otomatis. Jika aplikasi Anda mencoba ulang request, sediakan dan gunakan kembali kuncinya sendiri. Lihat Idempotency.

Langkah selanjutnya

Mengotorisasi channel adalah yang diperlukan channel private- atau presence- sebelum klien dapat berlangganan.
Ringkasan Realtime menjelaskan channel, member, dan koneksi, serta di mana penggunaan ditampilkan.
Mengecualikan penerima event mencegah klien yang melakukan aksi menerima perubahannya sendiri.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Jelajahi kemampuannyaRealtime Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first realtime event

Coba praktiknya dan dapatkan ringkasan implementasi