Send your first realtime event

Realtime delivers events over WebSockets. Your server publishes to a channel, and each connected client subscribed to that channel receives the event. This guide follows one path: create an app, subscribe a client, and publish from your server.

The free plan covers 100 concurrent connections and 200,000 messages per day, across all of a workspace's apps. Paid plans start at $25 per month; see Realtime pricing.

1. Create an app

An app is an isolated environment with its own credentials and channels. You choose its region when you create it, and you cannot change that region later.

Open Realtime > Apps in the dashboard.
Select Create app.
Enter a name in Name.
Select a Region: United States (us1) or Europe (eu1).
Select Create app.

Save your app credentials then shows three values, once:

App ID is a rap_… id that identifies the app in Bird API calls.
Key is public. Clients connect with it, and it is safe to ship in client code.
Secret pairs with the key to authenticate server-side calls and to sign channel authorization. Treat it like a password.

Copy all three before selecting I've saved my secret, because the secret is not shown again. Then create a Bird API key with the realtime scope on the Developers > API keys page, and export what the next steps need:

Przykład kodu

export BIRD_API_KEY="bk_us1_..."
export BIRD_REALTIME_KEY="your-app-key"
export BIRD_REALTIME_SECRET="your-app-secret"

Choose from three clients, one per platform, all speaking the same protocol: @messagebird/realtime for the browser, BirdRealtime for Apple platforms, and com.messagebird:bird-realtime for Android and the server JVM.

npm install @messagebird/realtime

// Package.swift, or Xcode's File › Add Package Dependencies
dependencies: [
    .package(url: "https://github.com/messagebird/bird-sdk-swift.git", from: "0.1.0")
]

// build.gradle.kts
dependencies {
    implementation("com.messagebird:bird-realtime:0.1.3")
}

The client identifies the app by its key and picks the edge from the region, so you do not configure a host:

import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
});

const orders = bird.subscribe("orders");
orders.bind("order-updated", (data) => {
  console.log("order changed", data);
});

import BirdRealtime

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1"
))

let orders = bird.subscribe("orders")
orders.bind("order-updated") { data in
    print("order changed", data ?? "")
}

import com.bird.realtime.BirdRealtime
import com.bird.realtime.BirdRealtimeOptions

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
    )
)

val orders = bird.subscribe("orders")
orders.bind("order-updated") { data ->
    println("order changed: $data")
}

All three clients open the socket as they are constructed, so you can subscribe without a separate connection call. Subscribing before the socket is up is fine too: channels are registered locally and sent as soon as the connection is established, and again after every reconnect.

orders is a public channel, so any client with the app key can subscribe. Channels named private-… or presence-… require your server to authorize each subscription. See Authorizing channels.

Channels are not created or configured anywhere. A channel exists while at least one connection is subscribed to it, and disappears when the last one leaves.

3. Publish from your server

Publishing is a server-side call. It authenticates with your Bird API key and carries the app's key and secret so the edge accepts it. Never publish from a client, because that would mean shipping the secret.

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"},
})
if err != nil {
	log.Fatal(err)
}

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

After the edge delivers the event, the subscribed client prints order changed { id: 42, status: 'shipped' }. If nothing arrives, check that the client key and server credentials belong to the same app and that the channel names match exactly. One publish can name up to 100 channels. To send up to 10 different events in one request, publish a batch.

Publishing resolves once the edge accepts the event. Delivery to connected clients is asynchronous, so a 200 means accepted rather than received.

4. See it in the dashboard

Realtime > Metrics shows peak and average concurrent connections and messages, per app or across the workspace. The charts report daily usage points, so use the client output from step 3 to confirm the event as it arrives.

Next steps

Authorizing channels covers private and presence channels, and the signature your backend returns.
Publish an event has the full request and response, including per-channel state at publish time.
Webhooks & events explains how to receive realtime.* events, such as a channel becoming occupied or a member joining, on your own endpoint.

Send your first realtime event

1. Create an app

2. Subscribe from a client

3. Publish from your server

4. See it in the dashboard

Next steps