Presence FAQ

13 questions on this page

Short answers to common questions about Presence.

What is Presence?

Presence tells your app who is subscribed to a channel right now, without polling. You can query a channel's occupancy, attach live state to a user, and receive join, leave, timeout, and state-change events through the same listener you use for messages.

Presence is live state, not stored state. It keeps no record after a client disconnects. For who belongs to a channel whether or not they are connected, use membership.

How do I turn on Presence?

Turn it on for your keyset in the Admin Portal. Presence must be enabled on the keyset, and new keysets have it enabled by default. See Enable the features your app calls.

Then choose which presence data your keyset generates in Presence Management, also in the Admin Portal.

On the client, subscribe with presence events enabled, and add a presence listener. The option is receivePresenceEvents in the JavaScript SDK, and the name varies by SDK. See Receive presence events.

When do presence events trigger?

• join fires when a client subscribes to a channel. A join event can arrive 1 to 2 seconds after the subscribe call, though it often arrives in under a second. If the same User ID connects from more than one device, each device produces its own join. For billing, the devices still count as one user.
• leave fires when a client unsubscribes cleanly.
• timeout fires when a client's connection drops and PubNub doesn't hear from it again before the presence timeout ends. PubNub SDKs set presenceTimeout to 300 seconds by default, which is how long PubNub waits without a heartbeat before marking a client offline. Connections don't always close cleanly, for example when a browser or app closes during network problems, and closing a browser tab doesn't always unsubscribe. In those cases, you get a timeout instead of a leave.
• state-change fires when a client changes its state with the state API. A client that passes state in the subscribe call doesn't trigger state-change. The state arrives in the join event instead.

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.

You set the Announce Max threshold and the interval in Presence Management in the Admin Portal. The keyset's Presence Interval setting, the cadence of interval events on a channel in interval mode, ranges from 10 to 3,600 seconds. See Presence events.

Can I adjust the presence timeout?

Yes. PubNub SDKs set presenceTimeout to 300 seconds by default, which is how long PubNub waits without a heartbeat before marking a client offline.

Set presenceTimeout and heartbeatInterval when you initialize PubNub. Some SDKs use other names for them. See Heartbeats decide when a timeout event fires.

Do client disconnects trigger leave events?

Not always. PubNub sends a leave event when the client unsubscribes from the channel, not by default when its network connection closes. To make sure a leave event fires, unsubscribe from the channel before the client disconnects.

PubNub doesn't always notice a network loss or a disconnect that isn't clean. In those cases, Presence sends a timeout when the presence timeout ends instead.

Can I add data to a User ID?

Yes. For data that lasts, such as a name or your own custom fields, use DataSync. For data that matters only while the user is subscribed to a channel, such as a mood or a typing indicator, use presence state. Presence state requires Presence enabled on the keyset, and disconnecting clears it.

Can I retrieve historical presence data?

Only the channel-level active and inactive events. PubNub publishes them on the keyset's Active Notice Channel. You can fetch them from history if Message Persistence has Include presence events selected. Presence keeps no other record. Occupancy, state, and the other events exist only while a client stays connected. See Channel active and inactive events.

Can I subscribe to presence events only?

Yes. Subscribe to the channel's presence channel, which is the channel name with the -pnpres suffix. Presence must be enabled on the keyset, and new keysets have it enabled by default. The presence channel carries join, leave, timeout, state-change, and interval events. See Presence events.

Can several clients use the same User ID?

Yes, for the same person. Use one User ID per person and reuse it on all of that person's devices and sessions, so the person counts as one monthly active user. Don't share one User ID between different people.

Each device's connection still generates its own presence events, so closing one tab while another stays connected can produce a leave followed by a join. See User ID.

Do presence events work with channel groups?

Yes. When a client subscribes to a channel group with presence, its join, leave, and state-change events fire on every channel in the group. Channel groups require the Stream Controller add-on enabled on the keyset. See Presence events.

Can PubNub call my server with a webhook when presence events occur?

Yes. Create an Events & Actions listener with the Presence event source, then pair it with a Webhook action that points to your HTTPS endpoint. You set both up in the Admin Portal, with no SDK code.

A listener can match presence events such as User started subscription to channel, User stopped subscription to channel, User timed out while subscribing to channel, and User state changed in channel. See Event sources and Create a Webhook action.

Why do I see presence usage with Presence disabled?

Your client configuration can still generate presence traffic, and each explicit heartbeat is a billable API call. Explicit presence heartbeats are off by default in PubNub SDKs, because heartbeatInterval defaults to 0.

In the JavaScript SDK, setting presenceTimeout also sets heartbeatInterval, which turns heartbeats on.

To stop the traffic, do all three:

1. Turn Presence off in the Admin Portal.
2. Remove the presenceTimeout and heartbeatInterval settings when you initialize the client.
3. Set suppressLeaveEvents to true.

These are the JavaScript SDK names:

const pubnub = new PubNub({
  publishKey: "myPublishKey",
  subscribeKey: "mySubscribeKey",
  userId: "myUniqueUserId",
  suppressLeaveEvents: true,
});

For the names in your SDK, see its configuration reference in the SDK docs.

How do I get the number of users on a channel?

Call Here Now, which lists the clients on a channel, on the channel. The occupancy field in the response is the number of clients currently subscribed. Presence must be enabled on the keyset, and new keysets have it enabled by default. To get only the count, without the list of User IDs, see Get only the occupancy count. For how the count is capped, see Channel occupancy.