Cache channels

A cache channel remembers its latest event and replays it to each new subscriber. A client that connects after an update can render the current state without waiting for another publish.

Use cache channels for current values such as a match score, device state, build progress, or order status. The subscription provides initial state and later updates.

Name a cache channel

The channel name enables caching. Put cache- at the start of the name or directly after its channel-type prefix.

Name	Cached	Subscription
cache-orders	yes	anyone holding the app key
private-cache-orders	yes	your backend signs for the client
presence-cache-lobby	yes	your backend signs, members tracked
orders-cache	no	anyone holding the app key

orders-cache is not a cache channel. The cache- prefix must lead the name after any private- or presence- prefix.

Everything else about the channel is unchanged. A private-cache- channel authorizes exactly like a private channel, and a presence-cache- channel still tracks members and fires member events like any other presence channel.

Subscribing

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

const match = bird.subscribe("cache-match-42");

match.bind("score-updated", (data) => {
  render(data);
});

match.bind("bird:cache_miss", () => {
  console.log("nothing cached for this channel yet");
});

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

let match = bird.subscribe("cache-match-42")

match.bind("score-updated") { data in
    render(data)
}

match.bind("bird:cache_miss") { _ in
    print("nothing cached for this channel yet")
}

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

val match = bird.subscribe("cache-match-42")

match.bind("score-updated") { data ->
    render(data)
}

match.bind("bird:cache_miss") {
    println("nothing cached for this channel yet")
}

On a hit, the cached event arrives after the subscription succeeds. It carries the original event name and payload, so the same handler processes cached and live events.

On a miss, the client receives bird:cache_miss on that channel. Either the channel has never received a publish or its cached event has expired.

Filling the cache on a miss

If an endpoint subscribes to realtime.cache_channels, the miss also reaches your server. Handle the webhook by reading the current state and publishing it to the channel.

await bird.realtime.publish(appId, {
  event: "score-updated",
  channels: ["cache-match-42"],
  data: await currentScore(42),
});

client.realtime.publish(
    app_id,
    event="score-updated",
    channels=["cache-match-42"],
    data=current_score(42),
)

_, err := client.Realtime.Publish(context.Background(), appID, bird.RealtimePublishParams{
	Event:    "score-updated",
	Channels: []string{"cache-match-42"},
	Data:     currentScore(42),
})

$bird->realtime->publish($appId, (new RealtimePublish())
    ->setEvent('score-updated')
    ->setChannels(['cache-match-42'])
    ->setData(currentScore(42)));

The client that caused the miss is subscribed before your server publishes the replacement event, so it receives the new state. This flow also populates an empty cache for its first subscriber.

Cache contents and retention

Events published through the API are cached, including single and batch publishes. Client events whose names start with client- are not cached.

Cached events can remain available for up to 30 minutes, but they may expire earlier. Repopulate infrequently updated channels from the cache-miss webhook instead of assuming the cache is still warm.

Each channel remembers only its most recent event. If you publish score-updated and then match-ended, a new subscriber receives only match-ended. Use one event name per cache channel, or include the complete state in every payload.

Cache limitations

A cache channel stores only the most recent event. It does not preserve an event history. A client that misses two updates while offline receives the latest state without the intermediate event. Keep durable state in your database. After reconnecting, the client re-subscribes and renders the cached event if one remains available. See Publishing events for delivery guarantees.

Next steps

Publishing events covers publishing from your server, batching, and broadcasting.
Private channels and Presence channels combine with cache- in the same name.
Querying channel state reads occupancy and counts from your server.