---
source_url: https://www.pubnub.com/docs/faq/presence
title: Presence FAQ
updated_at: 2026-10-27T09:13:26.000Z
---

# Presence FAQ

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

Short answers to common questions about [Presence](https://www.pubnub.com/docs/presence/overview.md).

## What is Presence?

[Presence](https://www.pubnub.com/docs/presence/overview.md) 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](https://www.pubnub.com/docs/presence/overview.md#presence-and-membership-answer-different-questions).

## How do I turn on Presence?

Turn it on for your keyset in the [Admin Portal](https://admin.pubnub.com/). Presence must be enabled on the keyset, and new keysets have it enabled by default. See [Enable the features your app calls](https://www.pubnub.com/docs/architecture/authentication/set-up-your-account.md#enable-the-features-your-app-calls).

Then choose which presence data your keyset generates in [Presence Management](https://www.pubnub.com/docs/presence/overview.md#turn-on-presence-without-writing-code), 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](https://www.pubnub.com/docs/presence/receive-presence-events.md).

## 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](https://www.pubnub.com/docs/presence/overview.md#turn-on-presence-without-writing-code) 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](https://www.pubnub.com/docs/presence/presence-events.md).

## 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](https://www.pubnub.com/docs/presence/presence-events.md#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](https://www.pubnub.com/docs/presence/overview.md) 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](https://www.pubnub.com/docs/data-storage/structured-data/overview.md). For data that matters only while the user is subscribed to a channel, such as a mood or a typing indicator, use [presence state](https://www.pubnub.com/docs/presence/set-and-get-presence-state.md). 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](https://www.pubnub.com/docs/data-storage/message-history/overview.md) 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](https://www.pubnub.com/docs/presence/presence-events.md#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](https://www.pubnub.com/docs/presence/presence-events.md).

## 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](https://www.pubnub.com/docs/architecture/core-concepts.md#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](https://www.pubnub.com/docs/presence/presence-events.md).

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

Yes. Create an [Events & Actions](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md) 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](https://www.pubnub.com/docs/integrations/event-forwarding/event-sources.md) and [Create a Webhook action](https://www.pubnub.com/docs/integrations/event-forwarding/create-webhook-action.md).

## 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:

```javascript
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](https://www.pubnub.com/docs/sdks.md).

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

Call [Here Now](https://www.pubnub.com/docs/presence/get-online-users-in-channel.md), 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](https://www.pubnub.com/docs/presence/get-online-users-in-channel.md#get-only-the-occupancy-count). For how the count is capped, see [Channel occupancy](https://www.pubnub.com/docs/presence/occupancy.md).

Last updated at: 2026-10-27T09:13:26.000Z