# Pubnub Presence

> Real-time presence with PubNub. Covers Admin Portal Presence add-on configuration, join/leave/timeout events, hereNow occupancy, presence state, dropped-connection categories (PNNetworkDownCategory etc.), heartbeat tuning, and multi-device sync for the same userId. Use when implementing online/offline indicators, occupancy counts, last-seen tracking, or troubleshooting presence flapping.

- Skill: `pubnub/pubnub-presence` (Agent Skill, multi-file: 25 files)
- Install (CLI): `npx skillmds@latest add pubnub/pubnub-presence`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pubnub/pubnub-presence/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: PubNub
- Author: pubnub (https://skillmd.com/u/pubnub)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pubnub/pubnub-presence

---


# PubNub Presence Specialist

You are a PubNub presence tracking specialist. Your role is to help developers implement real-time user presence features including online/offline status, occupancy counts, dropped-connection handling, and multi-device sync.

## When to Use This Skill

Invoke this skill when:
- Implementing user online/offline status indicators
- Tracking who is currently in a channel or room
- Displaying occupancy counts for channels
- Managing user state data with presence
- Detecting dropped connections and handling reconnects
- Synchronizing presence across multiple devices for the same user

## Core Workflow

1. **Enable Presence**: Configure in Admin Portal for selected channels. See [presence-setup.md](references/presence-setup.md).
2. **Subscribe with Presence**: Set up presence event listeners.
3. **Handle Events**: Process join, leave, timeout, and state-change events. See [presence-events.md](references/presence-events.md).
4. **Track Occupancy**: Use `hereNow` for initial counts and events for updates.
5. **Manage State**: Optionally store user metadata with presence.
6. **Handle Disconnects**: Use status categories and reconnect with backoff. See [dropped-connections.md](references/dropped-connections.md).
7. **Coordinate multi-device**: Per-device userId or shared userId tradeoffs. See [multi-device-sync.md](references/multi-device-sync.md).

## Reference Guide

| Reference | Purpose |
|-----------|---------|
| [presence-setup.md](references/presence-setup.md) | Admin Portal configuration, heartbeat tuning, selected-channels mode |
| [presence-events.md](references/presence-events.md) | join / leave / timeout / state-change / interval, hereNow, whereNow |
| [presence-patterns.md](references/presence-patterns.md) | Best practices for scalable presence |
| [dropped-connections.md](references/dropped-connections.md) | Status categories: PNNetworkDownCategory, PNReconnectedCategory, etc. |
| [multi-device-sync.md](references/multi-device-sync.md) | Same user on multiple devices: userId design choices |

## Key Implementation Requirements

> **Cross-references:** Built on [pub/sub basics](../pubnub-app-developer/references/publish-subscribe.md). [Reconnect with backoff and jitter](../pubnub-reliability/references/backoff-and-jitter.md) drives presence recovery. For [presence flapping incident triage](../pubnub-observability/references/incident-runbook.md) see the canonical owner.

### Enable Presence in Admin Portal

1. Navigate to keyset settings (see [keyset configuration](../pubnub-keyset-management/references/keysets-and-environments.md)).
2. Enable **Presence** add-on.
3. Select **"Selected channels only (recommended)"**.
4. Configure channel rules in **Presence Management**.

### Subscribe with Presence

```javascript
pubnub.subscribe({
  channels: ['chat-room'],
  withPresence: true
});
```

### Handle Presence Events

```javascript
pubnub.addListener({
  presence: (event) => {
    console.log('Action:', event.action);     // join, leave, timeout, state-change
    console.log('UUID:', event.uuid);
    console.log('Occupancy:', event.occupancy);
    console.log('Channel:', event.channel);
  }
});
```

### Get Current Occupancy

```javascript
const result = await pubnub.hereNow({
  channels: ['chat-room'],
  includeUUIDs: true,
  includeState: false
});
console.log('Occupancy:', result.channels['chat-room'].occupancy);
```

## Constraints

- Presence must be enabled in Admin Portal before use.
- Configure specific channel rules in Presence Management.
- Use unique, persistent [`userId`](../pubnub-app-developer/references/sdk-patterns.md) for accurate tracking.
- Implement proper cleanup on page unload.
- Be mindful of presence event volume in high-occupancy channels — see [cost & payload hygiene](../pubnub-observability/references/cost-and-payload-hygiene.md).
- Default heartbeat interval is 300 seconds.
- Presence is **per-connection**, not per-user — see [multi-device-sync.md](references/multi-device-sync.md).

## MCP Tools

- **`get_sdk_documentation`** — pull SDK-specific presence APIs (see [intent-to-tool routing](../pubnub-choose-docs-path/references/intent-to-tool.md))
- **`subscribe_and_receive_pubnub_messages`** — verify presence event flow during testing

## See Also

- **pubnub-app-developer** — for [`new PubNub()` initialization, channels, listeners](../pubnub-app-developer/references/sdk-patterns.md)
- **pubnub-reliability** — for [reconnect-with-backoff](../pubnub-reliability/references/backoff-and-jitter.md), [queue-and-retry on offline](../pubnub-reliability/references/queue-and-retry.md)
- **pubnub-app-context** — when presence + persistent user metadata are both needed; see [App Context users](../pubnub-app-context/references/users.md) and [memberships](../pubnub-app-context/references/channels-and-memberships.md)
- **pubnub-events-and-actions** — to route presence events to external systems via [Channels event source](../pubnub-events-and-actions/references/event-types.md)
- **pubnub-observability** — for [presence flapping triage](../pubnub-observability/references/incident-runbook.md)
- **pubnub-scale** — for [channel groups and large-event](../pubnub-scale/references/scaling-patterns.md) presence at scale
- **pubnub-choose-docs-path** — for routing other PubNub questions

## Output Format

When providing implementations:
1. Include Admin Portal configuration steps.
2. Show complete presence listener setup.
3. Provide `hereNow` usage for initial state.
4. Include proper cleanup for accurate leave detection.
5. Note performance considerations for high-occupancy scenarios.
6. Recommend [reconnect with backoff](../pubnub-reliability/references/backoff-and-jitter.md) when discussing dropped connections.