For AI agents: this page in Markdown: https://www.pubnub.com/docs/presence/occupancy.md. Documentation index: https://www.pubnub.com/llms-full.txt.

Channel occupancy

Occupancy is the number of clients currently subscribed to a channel. Presence reports it two ways: on demand, by calling Here Now, and continuously, through the occupancy field every presence event carries. This page explains:

  • what a Here Now response contains beyond the raw count
  • why that response is briefly cached, and why count-only mode keeps it flat regardless of how large the channel gets
  • why the member list is capped and paginated while the occupancy count itself never is
  • what changes, and what doesn't, once a busy channel switches to interval mode

An untracked channel returns the same occupancy: 0 and empty occupant list as an empty channel, so a zero Here Now result is not proof that the channel has no subscribers. Check your Presence Management rules before relying on it.

This page doesn't cover the Here Now or Where Now method syntax. For more information, refer to Presence, Get subscribed channels for a user, and Get online users in a channel.

What a Here Now response contains​

Call Here Now on a channel and PubNub answers with three things:

Here Now is the fetch counterpart to presence events. Use it once to seed a screen, such as an online-friends list, then switch to events to keep that screen current. Refer to Presence for that pattern and to Get online users in a channel for the call itself.

Ask for less and the response shrinks accordingly. The following illustrates a count-only response:

1{
2  "totalChannels": 1,
3  "totalOccupancy": 3,
4  "channels": {
5    "chats.room1": {
6      "name": "chats.room1",
7      "occupancy": 3,
8      "occupants": []
9    }
10  }
11}

That shape stays the same whether the channel has 3 occupants or 3,000. Only the occupancy number changes. occupants stays empty because count-only mode asked for a number, not a roster. Refer to Get online users in a channel for the option that turns count-only mode on and for the full response with occupants and state included.

Count-only mode keeps the response flat​

Returning the full roster costs more the busier a channel gets. PubNub has to list out every occupant and, if you asked for it, every occupant's state.

Count-only mode skips that step, so its response size doesn't grow with occupancy. Reach for it whenever your application only needs the number, such as an "N people online" badge that never lists who they are. Reach for the full response instead when you display or act on individual occupants.

Here Now is a point-in-time snapshot​

Here Now returns the occupancy at the moment the server handles the request. The count is accurate at that moment, but a client that calls it in a tight loop pays for each call without getting live tracking.

Use presence events to track occupancy as it changes, and call Here Now only when you need a confirmed snapshot (such as right after reconnecting).

Member lists paginate, but occupancy count doesn't​

A single Here Now call returns up to 1,000 occupants per channel, and you paginate past that with offset. That cap applies to the occupant list only. The occupancy number in the same response is always the true, uncapped total.

A channel with 5,000 subscribers reports occupancy: 5000 on every call, even though a single call's occupants array holds only the first page of their User IDs.

Page through the rest with repeated calls at increasing offset values. Refer to Get online users in a channel for the parameter.

Wildcards require a channel group​

Here Now takes a channel name, a list of channel names, or a channel group. It doesn't accept a wildcard pattern such as chats.*. Wildcard matching is a subscribe-time concept, based on whatever channels currently carry traffic, and Here Now needs a fixed target to query.

If your subscribers use a wildcard pattern, put the same channels in a channel group and query the group instead. Refer to Channels and channel naming for how one naming convention feeds both a wildcard pattern and a channel group.

Occupancy on a channel in announce vs interval mode​

Presence events run in one of two modes: announce and interval. A channel's occupancy is what decides which.

Below the Announce Max threshold, a channel emits individual join, leave, and timeout events. At or above it, the channel emits periodic interval events instead, while state-change stays individual in both modes. The Announce Max threshold is configured in Presence Management. For the full mechanics, refer to Presence events.

Here Now doesn't change with it. It keeps returning the same occupancy, occupants, and state for a channel in interval mode as for one in announce mode. The occupancy field on the interval event stays accurate too. What stops at the threshold is the per-client event stream, not the count.

That makes Here Now more useful on a busy channel. Presence webhooks stop firing once a channel passes that threshold. A server that tracked occupancy through webhooks loses that signal exactly when the channel gets busy enough to need it. Refer to API limits for the threshold's default and maximum. Polling Here Now, or subscribing to the channel's interval events directly, is what still works above it.

An interval event's optional delta arrays can also get dropped, if including them would push the event past the platform's message size limit. When that happens, the event carries hereNowRefresh: true instead of the deltas. Treat that flag as a prompt to call Here Now, since the roster you'd have gotten from the deltas didn't arrive. Refer to Presence events for the full payload.

Next steps​

Was this page useful?

Last updated on