---
source_url: https://www.pubnub.com/docs/design-patterns/build-roster-large-room
title: Build a roster for a large live event
description: Keep a server-side list of User IDs for one live event channel, read it through paged Here Now calls, and relay the count to viewers.
updated_at: 2026-11-20T09:51:54.000Z
---

# Build a roster for a large live event

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

This guide shows you how to build a server-side roster of User IDs for one live event channel. Build a roster only when the product needs names. If a viewer count is enough, use [Show a viewer count for a large live event](https://www.pubnub.com/docs/design-patterns/show-viewer-count-large-room.md) instead. Read [Large-room presence for live events](https://www.pubnub.com/docs/design-patterns/large-room-presence.md) first for what the roster can and can't guarantee.

Before you start:

* Turn on **Presence Deltas** in the keyset's Presence settings. The roster reads User IDs from `join`, `leave`, and `timeout` arrays.
* Run one roster service per event channel, not one per viewer.

The roster service works like this:

```mermaid
flowchart LR
    V["<b>Viewers</b><br/>subscribed to live.keynote-2026<br/>with heartbeats, no presence events"]
    CH["live.keynote-2026"]
    PRES["live.keynote-2026-pnpres<br/>(interval events with deltas)"]
    RS["<b>Roster service</b><br/>(your server)"]
    HN["Here Now<br/>(paged)"]
    COUNT["count.keynote-2026<br/>(signal with the count)"]
    API["Your roster API<br/>(first 50, search, friends)"]

    V --> CH
    CH -.-> PRES
    PRES --> RS
    RS <--> HN
    RS --> COUNT
    COUNT --> V
    RS --> API
    V <--> API

    class RS emphasis
    class PRES,HN muted
```

## Build the roster

1. Subscribe the service to the channel's `-pnpres` companion channel before you read the room. Buffer the events that arrive. Subscribing to `-pnpres` doesn't make the service an occupant, so the count isn't inflated.
2. Read the room with `Here Now`. Set `limit` to the largest value PubNub accepts, and never ask for a large room in one unpaged call. `Here Now` accepts a `limit` of up to 1,000 occupants per channel, and you paginate past that with `offset`. Send `limit` on every call. Increase `offset` by `limit` after each page. Stop when a page returns fewer User IDs than `limit`. Store the User IDs in a set.
3. Replay the buffered events. For each `interval` event, remove the User IDs in `leave` and `timeout`, and add the User IDs in `join`. Below Announce Max, apply individual `join`, `leave`, and `timeout` events the same way.
4. If an `interval` event has `hereNowRefresh: true`, read the room again. Never run two reads at once. If the flag arrives during a read, queue one more read after it finishes.
5. After each interval, compare the roster's size with the event's `occupancy`. If they differ for two intervals in a row, read the room again.

Don't calculate the number of pages from `occupancy`. A page can hold several times `limit` User IDs.

## Look up names

Look up each User ID in your own user store, in [DataSync](https://www.pubnub.com/docs/data-storage/structured-data/overview.md) user records, or in [App Context](https://www.pubnub.com/docs/data-storage/metadata/overview.md) user metadata. Cache the results. Presence carries User IDs, not profiles.

## Relay the count to viewers

If you relay the count, viewers don't subscribe to presence events. They still subscribe to the event channel and send heartbeats. They seed the badge with one count-only `Here Now` call, as in the count-only design.

1. On each `interval` event, publish the `occupancy` as a [signal](https://www.pubnub.com/docs/pub-sub/publish/send-different-message-types.md#send-a-signal-instead-of-a-message) to a count channel, such as `count.keynote-2026`. Signal payloads are limited to 64 bytes.
2. If the room is at or below Announce Max, also publish the count after each individual `join`, `leave`, and `timeout` event. Use the same rule as the [viewer code](https://www.pubnub.com/docs/design-patterns/show-viewer-count-large-room.md) to skip stray events from a busy room.
3. If the last relayed count was above Announce Max and no new count arrives for a few intervals, fall back to a count-only `Here Now` call. At or below Announce Max, silence is normal.

Send signals and messages on separate channels. Mixing them on the same channel interferes with how the SDK recovers missed events after a disconnect.

Leave the count channel out of your Presence Management rules.

## Set Access Manager grants

If [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) is on, grant these permissions:

* When [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) is enabled, calling `Here Now` requires `read` permission on the queried channel.
* When [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) is enabled, receiving presence events requires `read` permission on the channel, which also grants access to its `-pnpres` companion channel.
* Viewers on the relayed count need `read` on the count channel.
* The roster service needs `read` on the event channel and `write` on the count channel.

## Related tasks

* [Show a viewer count for a large live event](https://www.pubnub.com/docs/design-patterns/show-viewer-count-large-room.md). Count-only badge with no roster.
* [Load test a large live event channel](https://www.pubnub.com/docs/design-patterns/load-test-large-room.md). Simulated viewers that check the roster.
* [Get online users in a channel](https://www.pubnub.com/docs/presence/get-online-users-in-channel.md). Count-only calls and paging through a large channel.

Last updated at: 2026-11-20T09:51:54.000Z
