---
title: "Cache channels"
description: "Cache channels replay their latest event to new subscribers, giving late arrivals current state without waiting for another publish."
canonical: "https://bird.com/docs/guides/realtime/cache-channels"
---

# 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](/docs/guides/realtime/private-channels), and a `presence-cache-` channel still tracks members and fires member events like any other [presence channel](/docs/guides/realtime/presence-channels).

## Subscribing

**TypeScript**

```typescript
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");
});
```

Examples: [TypeScript](/docs/guides/realtime/cache-channels.ts.md) · [Swift](/docs/guides/realtime/cache-channels.swift.md) · [Kotlin](/docs/guides/realtime/cache-channels.kotlin.md)

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.

**TypeScript**

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

Examples: [TypeScript](/docs/guides/realtime/cache-channels.ts.md) · [Python](/docs/guides/realtime/cache-channels.py.md) · [Go](/docs/guides/realtime/cache-channels.go.md) · [PHP](/docs/guides/realtime/cache-channels.php.md)

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](/docs/guides/realtime/publishing-events) for delivery guarantees.

## Next steps

- [Publishing events](/docs/guides/realtime/publishing-events) covers publishing from your server, batching, and broadcasting.
- [Private channels](/docs/guides/realtime/private-channels) and [Presence channels](/docs/guides/realtime/presence-channels) combine with `cache-` in the same name.
- [Querying channel state](/docs/guides/realtime/querying-channel-state) reads occupancy and counts from your server.

## Related resources

- [Realtime](/realtime-api) (product)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first realtime event](/docs/get-started/send-your-first-realtime-event) (docs)

[Get an implementation brief](/learn/workspace?topic=realtime)