Presence Management

When you create a new keyset in the Admin Portal, Presence is enabled by default.

The default configuration, however, turns off all presence events. This means that you cannot monitor channel members' subscription status, track any Presence-related events, for example, when users join or leave the channel, or when their presence state changes.

Subscription with Presence

You must create a subscription with Presence enabled to receive Presence events. For more information, refer to each SDK's Publish and Subscribe documentation.

To track Presence events, use Presence Management — a self-service tool that lets you create rules defining which Presence events you want to track on which channel patterns.

Existing Presence rules

If you already have Presence rules created by PubNub support, they remain valid and will be visible on the Admin Portal.

To start managing presence rules, follow these steps:

1. Log into the Admin Portal.

2. Go to the BizOps Workspace section in the left navigation panel.

3. Select Presence Management.

4. Choose an app and a keyset on which you want to manage channels.

5. If you don't have Presence enabled on your keyset, you will be requested to enable it at this point by following on-screen instructions. You need to decide on the default setup - whether you want to track all Presence events on all channels (* pattern) or not.

   

   If you decide on ALL OFF at this point, you will see this general setup as a raw on the Presence rules list.

   

   You can change this setting at any point by clicking Edit rules and toggling the slider.

   You can also create channel- and event-specific Presence rules, which will take precedence over this generic setup.

Create Presence rules

1. Once in the Presence Management module of BizOps Workspace, click the Edit Rules button to switch to the configuration mode.

   

2. Click the Create rule button.

   

   A new rule placeholder will appear as a row at the top of the list.

   

3. In the Channel pattern column, type in the channel name or the wildcard pattern for the channels you want to enable Presence on. For example, enter personal-* to track Presence on all channels with the personal prefix.

   Rule limitations

   If you want to include a few patterns, you must create additional rules as one rule can follow only one allowlist pattern.

4. In the Publish Events column, select the types of events you want to track on the previously defined channels or channel patterns.

   Events	Description
   Join	Fires when a user subscribes to a channel.
   Leave	Fires when a user unsubscribes from a channel.
   Timeout	Fires when a connection to a channel is lost and the subscriber hasn't been seen in 300 seconds.
   State-change	Fires whenever the user's state changes.
   Interval	Fires in interval mode to provide an occupancy count and optionally include delta changes.

5. For Subscribe heartbeats and Presence heartbeats, select how often the client should announce its presence to the PubNub server.

   By default, both settings are enabled, but only one is required to track events (of any type) for a given rule.

   Timeout events	Description	Required client configuration	Cost efficiency
   Subscribe heartbeats	PubNub's subscribe heartbeats function similarly to long polling to manage client presence by sending periodic requests at a given interval. This default interval can vary based on the SDK (like every 300 seconds) and is configurable during client initialization. These requests ensure the client remains active on subscribed channels. If no heartbeat is received within the timeout period, the client is marked inactive, triggering a "timeout" event on the presence channel.	This setting is enabled by default on the client. It can be configured during client initialization and the name of the parameter can vary depending on the SDK, like presenceTimeout in JavaScript SDK.	Subscribe heartbeats are billed separately from presence heartbeats.
   Presence heartbeats	These heartbeats offer more granular control over client activity tracking than subscribe heartbeats. If a shorter Presence timeout is needed, Presence heartbeats must be manually configured during client initialization. This involves setting an interval for heartbeat signals, typically recommended to be calculated according to this formula: (presenceHeartbeatValue / 2) - 1.	Must be configured on the client. It can be configured during client initialization and the name of the parameter can vary depending on the SDK, like heartbeatInterval in JavaScript SDK.	Presence heartbeats are billed separately from subscribe heartbeats.

6. By default, a new rule is created at the bottom of the rules list with the lowest execution priority. To increase the rule priority, hover over it and move it up the list.

7. When you're done, click Save to finish.

   The new rule will appear on the rules list.

   

Change rules order

Each rule created through Presence Management gets a unique number that denotes the rule execution sequence. Rules on top take precedence over the subsequent rules. If there are two mutually exclusive rules, the one higher on the list will be respected.

You can change the order of rules by clicking the Edit Rules button to switch to the configuration mode, hovering over a given rule, moving it up or down the list, and clicking Save.

Edit rules

To edit a rule, click the Edit Rules button, change the settings, and Save the configuration.

Copy rules

To easily create numerous rules with similar setups (publish events), you can use the "Copy" icon that creates a copy of the original rule underneath the original rule, with a place for a channel pattern you must fill in.

Click the Edit Rules button to switch to the configuration mode, copy a given rule, complete the rule setup, and Save the configuration.

If you create a new rule with a pattern already covered by another rule, you'll receive a warning that this rule doesn't apply.

Delete rules

To delete a rule, click the "Bin" icon next to the rule and Save the configuration.

Configure webhooks for rules

Once you have created Presence rules, you can configure webhooks for them using Events & Actions. This way, you can decide what will happen when chosen Presence events occur. For example, you can configure Events & Actions to send e-mail notifications each time a new member joins a channel.