Large-room presence for live events

This page explains what Presence reports for one event channel with tens of thousands of viewers, and what a live-event design has to account for. The examples assume that Presence Management tracks the event channel. The page doesn't repeat the Presence application programming interface (API) reference.

Start with what Presence gives you at this size, and what it doesn't:

  • A snapshot count when you ask for one. A count-only Here Now call returns the occupancy at the moment the server handles the request.
  • A periodic count after that. Once the room is busy, the channel reports its occupancy in an interval event every few seconds, instead of on every arrival. Each event is a snapshot PubNub cut up to one interval before you see it.
  • No complete, instantly accurate list of 40,000 names. If your product needs names, your server builds that list from paged Here Now calls and presence deltas. The list always trails the room, and it's never complete while the room is filling.

Test results on this page come from simulated events run on November 6, 2026, on a testing keyset that counted only explicit heartbeats, with Announce Max 20, a 10-second interval, and presence deltas on. The main run filled one channel with 40,000 simulated viewers in about a minute, from a single machine. The results describe those runs. They aren't platform limits.

Start with one channel and a count​

Put every viewer on one event channel, such as live.keynote-2026. The number of subscribers on a PubNub channel is unlimited. You don't need to split the audience to count it. Each viewer subscribes to that channel, sends heartbeats, and renders the channel's occupancy. For a viewer count, that's the whole design.

A roster of named viewers is a separate requirement with a separate cost. Before you build one, decide what the product shows:

What the product showsWhat to buildHow current it is
A viewer count, such as "40,213 watching"Viewers subscribe with presence events and render occupancy from interval events. Leave presence deltas off.A count-only Here Now call is a snapshot of the moment the server handled it. Each interval event is a snapshot cut up to one interval earlier.
A count and names, such as "who's here" or "friends watching"A roster service on your server, and an API that returns the slice of names a screen needs. Your server sends viewers the count.Behind by at least one interval plus one full read of the room. In testing, the roster was never complete during a 62-second join burst and first matched the room 12 seconds after the last viewer arrived.

Nobody scrolls through 40,000 names. A screen shows the first 50, a search box, or the viewer's friends. Design the roster API around those queries, and no client ever downloads the whole room.

What changes when 40,000 people arrive in a minute​

The channel stops announcing each viewer​

Up to the Announce Max threshold, a channel emits individual join, leave, and timeout events. Above it, the channel emits periodic interval events instead, while state-change stays individual. You set the threshold with the Announce Max setting in Presence Management. API limits gives its default and maximum. In a room that fills to 40,000, the viewers up to the threshold produce individual join events. Everyone after them is folded into interval events.

An interval event carries the channel's current occupancy. It arrives on schedule whether or not anything changed, and PubNub sends each one to every viewer subscribed with presence events. With 40,000 viewers and a 10-second interval, that's 4,000 presence events a second to keep a badge current. If a count that's 30 seconds old is good enough, raise the interval.

The switch works in both directions. When the room drops back to Announce Max, individual leave and timeout events come back. In testing, an interval event reporting the threshold arrived first.

The diagram shows the two event modes, the events each one sends to viewers and webhooks, and what moves the channel between them.

Individual events can carry a partial count​

Once a room is above Announce Max, don't take the count from individual join, leave, or timeout events. During a simulated 40,000-viewer burst, the channel was in interval mode with about 10,000 viewers when 20 join events arrived with occupancy values between 4 and 20. A badge that rendered every event's occupancy showed "20 watching" for 8 seconds, until the next interval event corrected it. Take the count from interval events and Here Now until the room drops back to the threshold. The viewer code in Show the count to every viewer does this.

Per-viewer webhooks stop​

Once a channel is above Announce Max, PubNub stops producing join, leave, and timeout events for it, so Events & Actions can't forward arrivals and departures one by one. A backend that tracks viewers from those events loses the signal exactly when the room gets big. The interval event, listed in Event sources as Interval occupancy counted, still goes out, and so do state-change events. A backend can take the count from the interval event. For names, build the roster on your server.

PubNub Support can turn on a keyset setting that keeps leave and timeout webhooks going above Announce Max. It doesn't bring back join, so a backend still can't follow arrivals one by one.

Presence deltas don't survive the join burst​

Presence deltas add join, leave, and timeout arrays of User IDs to each interval event. PubNub drops an interval event's delta arrays once the full event passes 30 KiB, which is roughly 680 changes with 36-character User IDs. That keeps the event inside the default message size limit. Longer User IDs lower the number of changes that fit. In testing, an interval with 650 User IDs in its deltas kept them, and one with 690 lost them. Every interval of a 40,000-viewer join burst arrived without deltas.

When PubNub drops the arrays, it sets hereNowRefresh to true. On the wire the field is here_now_refresh, and it's absent when false. The JavaScript software development kit (SDK) reports it as hereNowRefresh: false in that case. A viewer that only shows a count can ignore the flag, because occupancy is still in the event. A roster service has to read the room again.

Presence deltas are a keyset setting, not a per-channel one, and PubNub sends them to every subscriber with presence events. A viewer that renders only a number would download tens of kilobytes per interval while the room churns. Leave deltas off for a count-only design. If a roster service needs deltas, stop viewers from subscribing to presence events and send them the count from your server.

The count trails arrivals by up to one interval​

A count-only Here Now call answers for the moment the server handles it. An interval event answers for the moment PubNub cut it, and the next one comes a full interval later. A badge driven by interval events trails the room by up to one interval.

In the simulated burst, the interval event at 12 seconds reported 9,866 viewers. A badge driven by interval events kept that number until the next event at 22 seconds, while the room grew to about 22,000. A viewer already in the room before the doors opened saw its badge climb to 20 through individual join events, then wait for that first interval event.

Count-only Here Now results fell within the range of viewers in the room while each call was in flight. That held for about 10,000 calls made by viewers right after they joined. During the burst, about 1,300 viewers arrived every second, so the range was several hundred viewers wide. Once the room settled, results matched the room exactly, apart from one viewer PubNub never counted, described in Plan for reconnects and departures.

Reads and heartbeats at scale​

A roster read that runs while viewers come and go isn't a snapshot. In the simulated 40,000-viewer room, one full read during churn missed 63 of the roughly 39,700 viewers present the whole time, and reads during the burst returned up to 335 User IDs twice. No later delta repairs a missed viewer, because the viewer's state doesn't change. That's why a roster service checks its set against occupancy after each interval.

Page sizes vary. In testing, 30,000 viewers came back in 11 pages, with the first pages holding 5,000 User IDs each. Page sizes for the same room changed from one read to the next, so don't predict the page count.

Heartbeats set most of the request load at this size. With 40,000 viewers, the recommended 60-second timeout and 29-second interval in API limits send about 1,380 heartbeats a second. The 120 and 59 second values in the viewer code halve that rate, and departed viewers stay counted up to a minute longer. A shorter presenceTimeout removes departed viewers sooner and costs more heartbeats.

The Admin Portal's Subscribe heartbeats (implicit) switch decides whether subscribe requests keep a viewer present. Turn it on only for viewers that can't send explicit heartbeats, such as older SDK versions that stay present through their subscribe requests. Current SDK versions don't work that way. In testing, a client on a keyset with the switch off stayed subscribed and still timed out of the count, so a viewer that sends no heartbeats drops out.

Build the design​

Three how-to guides cover the build steps:

Plan for reconnects and departures​

These are the cases that move the count in ways a viewer doesn't expect. Unless a case says otherwise, it was reproduced in the simulated room or in a small companion test.

  • Reconnecting with the same User ID changes nothing. A viewer that drops off the network and comes back before presenceTimeout expires produces no event and no change in the count.
  • Coming back after the timeout counts as a departure and a new arrival. The room sees a timeout, then a join when the viewer's next heartbeat arrives.
  • A fresh User ID on every page reload counts the viewer twice. When 1,000 viewers reloaded with new IDs, the count rose by 1,000 within about 3 seconds and stayed there until the old IDs timed out, up to a minute later with a 60-second presenceTimeout. Store the User ID with the viewer's account or in local storage, and reuse it.
  • One User ID on two devices flickers. When one tab unsubscribed, the room saw a leave immediately, then a join when the other tab's next heartbeat arrived, up to one heartbeatInterval later.
  • Leaving and rejoining within seconds can lose the viewer. In the 40,000-viewer run, one of 200 viewers that left and sent a heartbeat 3 seconds later wasn't counted again, although its heartbeat succeeded. That simulated viewer sent no further heartbeats, so it stayed uncounted for the rest of the test. To reconnect, keep the subscription and let heartbeats continue, rather than unsubscribing and subscribing again.
  • Viewers who close the tab stay counted until presenceTimeout expires. PubNub reports the timeout in the next interval. Unsubscribe when a viewer leaves the event inside your app, so PubNub sends a leave right away. For tab closes, refer to the Generate Leave on TCP FIN or RST option in Presence Management. That option wasn't part of the test.

When the event ends, expect a second burst. In the test, about 37,000 simulated viewers that had joined during the first minute sent no further heartbeats, with the default presenceTimeout. They left the count over about a minute, each roughly one presenceTimeout after its heartbeat. Every interval in that minute arrived with hereNowRefresh: true. A real audience leaving at the end of a stream produces the same pattern, compressed into whatever window people close the tab in.

Next steps​

  • Occupancy. What a Here Now response contains and why the count stays accurate in interval mode.
  • Presence events. Announce and interval modes, presence deltas, and heartbeat timing.
  • Get online users in a channel. Count-only calls and paging through a large channel.
  • Presence Management. Rules, Announce Max, interval, and deltas.
  • Rate limiting. Keep a very large channel usable once it carries messages too.
  • API limits. Announce Max, interval range, recommended heartbeat settings, and webhook limits.

Was this page useful?

Last updated on