Subscriptions

As PubNub allows you to have hundreds or even thousands of subscriptions, it's vital to understand how to manage them efficiently.

icon

Understanding the subscribe loop


Read on to understand what subscriptions and subscription sets are, and how to manage multiple channels with channel groups, wildcards, and Message Filters.

Receiving messages

To receive and handle incoming messages, signals, and events, you have to add an event listener first. If you're new to PubNub, make sure to check out how to set up your account as well.

Subscription types​

The basic types of subscriptions are entity-scoped subscriptions and subscription sets. Within the PubNub SDKs, they are represented as Subscription and SubscriptionSet (although naming may vary between SDKs). For more information, refer to Entities.

Entity-enabled SDKs

Not all PubNub SDKs currently support entities. Refer to each SDK's API documentation for more information.

icon

How we did subscriptions in the past


Subscription typeWhen to useSample usageBenefits
Subscription
When you want to introduce more granularity and flexibility to the way you handle particular events.
If you want to handle the same message differently on two (or however many) channels, you can create a separate subscription for each channel and attach different event listeners.
  • Create multiple subscription objects that can be activated/deactivated without affecting others
  • Event handlers tied to specific subscriptions eliminate complex conditional logic
  • Multiple subscriptions are multiplexed over a single connection
SubscriptionSet
When you want to introduce common functionality to a number of events.
If you want to have a common logic for specific updates (for example, handling status updates), you can create a subscription set with all channels where user's presence is to be monitored and attach a single event listener.
  • Manage multiple channels as a group without tracking global state
  • Apply the same event handling logic across multiple channels
  • Each component can manage its own subscription set

Both Subscription and SubscriptionSet objects have intuitive interfaces for subscription-related operations (like switching between the active and inactive states) and working with listeners. On top of that, you can create subscription sets from existing entity-scoped subscriptions if you decide you need to handle a bunch of subscriptions similarly.

icon

Sample usage


Subscription options​

You can parametrize the real-time data stream created using the Subscription and SubscriptionSet objects by specifying optional subscription options. Those options are shared across SDKs although you have to consider programming language differences in naming conventions.

Available options include:

Subscription optionDescription
filter
Allows you to specify arbitrary filtering for events coming through the subscription.
receivePresenceEvents
Allows you to decide whether to receive presence updates.

For more information on how to use the subscription options in each SDK, refer to each SDK's Subscribe section of the API documentation, for example, in JavaScript.

Create subscriptions​

Each SDK has dedicated methods to create subscriptions and subscription sets. For more information on managing subscriptions, refer to each SDK's Subscribe section of the API documentation, for example, JavaScript.

Receiving events on subscriptions​

You can assign functions directly to event-specific properties on the subscription object. This approach provides a clean, straightforward way to handle specific events.

const channelSubscription = pubnub.channel('channel_name').subscription();
channelSubscription.subscribe();

// Handle messages
channelSubscription.onMessage = function(message) {
  console.log('Received message:', message);
};

// Handle presence events
channelSubscription.onPresence = function(presenceEvent) {
  console.log('Presence event:', presenceEvent);
};

// Other handlers are available for signals, objects, files, and message actions

This method allows for clear, direct assignment of handlers to specific event types and is particularly useful when you want to add or change handlers dynamically.

For more information on how to use the on[Event] syntax, refer to each SDK's API documentation, for example, JavaScript.

Both approaches achieve the same result, so you can choose the style that best fits your application's architecture and your team's preferences. The specific syntax may vary slightly between SDKs, so refer to your SDK's documentation for details.

Subscribe to Channels​

Once the listener object is established, the client can request to subscribe to individual channels. Subscribing to channels initiates a connection with the PubNub Platform which triggers a connection status event. This connection is kept open for the duration that the client stays subscribed to at least one channel. Any user subscribing to a channel receives messages in under 30ms, regardless of location.

Default subscribe timeout

There is a default timeout of 310 seconds (~5 min) for all requests related to subscribed channels that the client sends to the server. You can reduce this limit in your client configuration by specifying a different value for the subscribeTimeout parameter.

The client can subscribe to several channels simultaneously through a single open connection. Typically, you subscribe to channels on app load. As the user navigates through your app, your app can remain subscribed to all the channels so it continues to receive messages on all of them. Alternatively, you can implement your app in a way that it subscribes and unsubscribes from channels as the user navigates through the app.

Configuration​

If you want a single client to subscribe to multiple channels, you must have the Stream Controller feature enabled on your app's keyset in the Admin Portal to use the following subscription options:

  • Channel Multiplexing — subscribing to multiple channels in a single API call
  • Wildcard Subscriptions — subscribing to groups of channels that share a common naming pattern, like news.*
  • Channel Groups — creating named groups of channels and then subscribing to the group as a whole

Contrary to other features that you must specifically enable, Stream Controller is active by default on all new keysets.

Stream Controller in Admin Portal

OptionDescription
Enable Wildcard Subscribe
An option that lets you subscribe to groups of channels with a shared naming pattern, like *.chat.*
Channel group limit
The maximum number of channels you can add to channel groups. The default limit of 1,000 channels applies to all new keysets and can be modified if you have a paid account — you can then either lower the limit or increase it up to 2,000 channels.

Signal Channel Subscribe​

To receive Signals, you don't need a different subscription to the channel, but you do need a separate signal event listener as mentioned in the Adding a Listener section.

Channel Multiplexing​

Subscribing to multiple channels from a single client is called multiplexing. You can subscribe to one or more channels by creating many individual subscription objects or subscription sets. You can also create individual subscriptions and create a subscription set from them when their number increases.

Multiplexing allows each client to subscribe to a combination of channels of their choosing and change that selection at any time.

Multiplexing is designed for a relatively small number of channels. While there is no hard limit, PubNub strongly recommends multiplexing no more than 30 channels for any subscribe, and possibly fewer if you are deploying a larger application. For bigger channel subscribe groupings, you should consider using Channel Groups.

You can subscribe to one or more channels in a single request or you can spread those requests out in your application's flow. For example, a client might subscribe to chats.room1 now and then later subscribe to chats.room2. Doing so will simply add chats.room2 to the current list of channels that have already been subscribed as if you subscribed to them at the same time.

For example, below is how you would subscribe to a channel chats.room1 when the user of your app enter their first chat room.

const channel = pubnub.channel('chats.room1');
channel.subscription().subscribe();

The user continues to use your application, and then decides to enter another chat room, chats.room2.

// create a subscription from a channel entity
const channel = pubnub.channel('chats.room1')
const subscription1 = channel.subscription({ receivePresenceEvents: true });

// create a subscription from a channel entity
const channelGroup = pubnub.channel('chats.room2')
const subscription2 = channel.subscription();

const subscriptionSet = subscription1.addSubscription(subscription2);
subscriptionSet.subscribe();

The result is that the user is now subscribed to both chat room channels.

You can also leverage Channel Groups and Wildcard Subscribe. Below you'll be briefly introduced to these two alternative subscription management features.

Enable Stream Controller

Multiplexing is available by default, regardless of your Admin Portal configuration. However, to use the Wildcard Subscribe and Channel Groups features, the Stream Controller add-on must be enabled on your keyset in the Admin Portal.

Channel Groups​

You can think of a channel group like a pointer to a list of channels on your server. If your application requires listening to large numbers of channels at once, channel groups allow you to send a single call which may subscribe to up to 100 channels. By default, each individual client can subscribe to a maximum of 10 channel groups for a total of up to 1,000 channels.

Modify limits for channels in channel groups

The default limit of 1,000 channels in channel groups per keyset applies to all new keysets created in the Admin Portal. If you're on a paid account, you can modify that limit for your app in the Admin Portal by changing the value for the Channel group limit on your keyset configuration under the Stream Controller section. You can either lower the default limit or increase it up to 2,000 channels.

Subscribe vs. Publish to Channel Groups​

Channel groups can also be thought of as a subscribe group, because you can only subscribe to a channel group and you can't publish to a channel group. There are definite advantages to using channel groups when your clients must subscribe to a lot of channels. Your server adds channels to a channel group and clients can subscribe to all those channels contained in the channel group simply by subscribing to that channel group.

Your clients may not need to listen to that many channels, but channel groups make it possible for your server to manage the channels that the client is subscribed to by adding and removing channels on behalf of the clients.

To use a channel group, instead of multiplexing, there is just one additional step: add channels to a channel group.

Add channels to a channel group. This also creates the channel group if it doesn't already exist. This should be performed by your server for security and ease of management.

pubnub.channelGroups.addChannels({
    channels: ["chats.room1", "chats.room2", "alerts.system"]
    channelGroup: "cg_user123"
  },
  function(status) {
      console.log(status);
  }
);

The client subscribes to the channel group.

const channelGroup = pubnub.channelGroup('cg_user123');
channelGroup.subscribe();

When messages are published to any of the channels in this channel group, it will be received in the message handler of the client's listener. The channel group subscribes can also be enabled with withPresence parameter to start receiving presence events for all the channels in the Channel Group.

Subscription with Presence

To receive Presence events, you subscribe with Presence and have Presence enabled on your keyset. Make sure you configure Presence to track Presence-related events for all or selected channels (through Presence Management rules).

Be aware of whether this is necessary for your use case or not. You can separate channels into two channels groups: cg_presence_user123 (channels with presence tracking) and cg_user123 (channels without presence tracking). This can all be done on the client app. but when we talk about channel access security (Access Manager), it will be clear why clients should never be able to add/remove channels to/from a channel group.

Additionally, with Channel Groups your server can force a client to unsubscribe from a particular channel just by removing that channel from the channel group that the client is subscribed to.

Channel Group Names​

Channel groups can be shared just like channels. For example, you may want to create a channel group called cg_sports. Multiple clients can subscribe to this shared channel group and your server can add new channels related to sports and all the clients will automatically be subscribed to those new channels.

And there is no requirement to prefix the name with cg_. It's only a convention that makes it easy to recognize Channel Groups. Feel free to use a naming convention that works best for your requirements and design style.

Channel Group Names

Channel Group names have the same rules as Channel names with one exception: you can't use a period in the name. This means that wildcard features do not apply to Channel Groups.

Just because you're using Channel Groups does not mean you can't also subscribe to individual channels. Sometimes it may be convenient to subscribe to a particular channel directly while also subscribing to a separate Channel Group. You can specify channels and channel groups in the same subscribe call or make individual subscribe calls. And channel groups can be multiplexed, too.

Wildcard Subscribe​

Wildcard Subscribe channelName.* can be used to subscribe to a hierarchical list of channels. It's similar to Channel Group in that you can subscribe to lots of channels with a single name declaration. For example, you specify a wildcard channel pattern like sports.*, and your app will subscribe to all channel names that match that pattern: sports.cricket, sports.lacrosse. This list can be virtually infinite in number with some limitations described in the next section.

const channel = pubnub.channel("alerts.*");
channel.subscription().subscribe();

Wildcard Subscribe Rules​

There are some limits to what you can do with the Wildcard Subscribe. Below is a quick summary of the rules:

  • You're limited to two dots (three levels). For example, you can subscribe to a.* or a.b.* but not a.b.c.*.
  • A wildcard pattern must always end with .*. In other words, the * can't be in the middle of the pattern (a.*.c, isn't valid).
  • Just like Channel Groups, you can not publish to a wildcard channel pattern.

Message Filters​

With the metadata information being sent with the published message, we can now leverage Message Filters to omit messages that aren't important for a particular client. For example, filter out messages that the client published using its User ID.

In the following code examples, the userId variable is used as a placeholder variable that would hold the User ID value for the client. For your servers, this value would be pulled from a server config file. For your clients, this value is received from your server after successful login.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

var pubnub = new PubNub({
  publishKey: "myPublishKey",
  subscribeKey: "mySubscribeKey"
  userId: userId
})

pubnub.setFilterExpression("userId != '" + pubnub.getUserId() + "'");

Filterable message properies​

Based on PubNub's capabilities, here are all the message items you can filter on when subscribing:

  • Message payload/content - The actual data content of the message
  • Message metadata - The metadata attached via the meta parameter when publishing
  • Publisher User ID - The unique identifier of the entity that published the message
  • Channel - The channel on which the message was published
  • Timetoken - The timestamp when the message was published
  • Message actions - Related actions performed on the message
  • Message type - Custom type identifiers if your application uses message typing
  • Presence events - If you're also handling presence events in your subscription
  • Signal messages - Lightweight message types can be filtered separately
  • File messages - Messages related to file uploads

The filtering syntax allows for complex expressions combining these elements using operators like equality checks, pattern matching (LIKE), and logical operators (AND, OR).

Subscribe Filtering vs. App Context Filtering​

PubNub offers two powerful filtering mechanisms that share similar syntax but serve different purposes in your real-time applications.

  • Subscribe Filtering - Used when subscribing to channels to control which messages are delivered to your client
  • App Context Filtering - Used when querying metadata to retrieve specific users, channels, or memberships

Both filtering systems:

  • Use the same expression syntax (==, !=, >, <, LIKE, &&, ||)
  • Support pattern matching with wildcards
  • Allow complex boolean expressions
  • Follow a similar format that evaluates to true/false

Key differences are as follows:

FeatureSubscribe FilteringApp Context Filtering
Purpose
Controls which messages reach subscribers
Queries metadata about entities
Target Data
Messages and their attributes
Users, channels, and memberships
When Applied
During active subscriptions
During metadata retrieval
Implementation
In subscribe method
In metadata query methods
Examples​

Subscribe Filtering:

// Only receive messages with high priority from the US region
pubnub.subscribe({
  channels: ['updates'],
  filter: 'message.priority == "high" && meta.region == "us"'
});

App Context Filtering:

// Only retrieve active support agent users
pubnub.objects.getAllUUIDMetadata({
  filter: 'status == "active" && type == "support_agent"'
});

While the syntax looks similar, notice how subscribe filtering operates on message properties and metadata, while App Context filtering works with entity attributes like status and type.

For more examples on how to use the filtering syntax, refer to App Context filtering.

Filter Language Definition​

The filtering language is extensive and supports many advanced use cases. Here are some common filter examples:

ExpressionMeaning
string == 'match'
Exact match
string LIKE 'match*'
Asterisk wildcarding, case insensitive
string LIKE 'match\*'
Literal match with string containing asterisk character
('Anne','anna','Ann') LIKE 'ann*'
Any of the three set members would be a sufficient match
('a','b','c') CONTAINS string
Compare against a list of values
otherstring CONTAINS string
Check for a substring match
(3,5,9) contains numValue
Compare number to a list of values
!((3,5,9) contains numValue)
Negation
string contains numValue
str(numValue) in string
numValue > (numA + numB - numC)
Compare number to an arithmetic expression
(numA ^ numB) != (numValue * 10)
Compare two expressions
(~numA / numB)
numValue
Filter Expression Language Specification​

compound_expression is root.

ExpressionComment
<compound_expression>
<expression> | <expression> <binary_logical_op> <expression>
<binary_logical_op>
&& | ||
<expression>
(<expression>) | <operand> <comparison_operator> <operand> | <unary_logical_op> <operand>
<numeric_comparison_operator>
{==, !=, <, >, <=, >=}
<string_comparison_operator>
{contains, like}
<unary_logical_op>
!
<operand>
(<operand>) | <unary_op> <operand> | <literals> <binary_op> <literals>
<unary_op>
~
<binary_op>
|, &, ^, +, -, /, *

Unsubscribe from Channels​

Unsubscribe from a channel to stop receiving its messages. You can use this method to unsubscribe from one or more channels.

// create a subscription from a channel entity
const channel = pubnub.channel('channel_1')
const subscription1 = channel.subscription({ receivePresenceEvents: true });

// create a subscription set with multiple channels
const subscriptionSet1 = pubnub.subscriptionSet({ channels: ['ch1', 'ch2'] });

subscription1.subscribe();
subscriptionSet1.subscribe();

subscription1.unsubscribe();
subscriptionSet1.unsubscribe();

Unsubscribe from all Channels​

Use this method to unsubscribe from all channels.

// create a subscription set with multiple channels
const subscriptionSet1 = pubnub.subscriptionSet({ channels: ['ch1', 'ch2'] });
subscriptionSet1.subscribe();

// create a subscription from a channel entity
const channelGroup = pubnub.channelGroup('channelGroup_1')
const subscription1 = channelGroup.subscription({ receivePresenceEvents: true });
subscription1.subscribe();

pubnub.unsubscribeAll();

Deprecation of Previous Subscription APIs​

As PubNub introduces the new entity-based subscription architecture across its SDKs, the previous global subscription APIs (such as pubnub.subscribe() and pubnub.unsubscribe()) are being marked as deprecated. However, to ensure a smooth transition for developers, each SDK supports a long end-of-life (EOL) period.

The deprecation timeline varies by SDK. For example, in the JavaScript SDK, the "old" pubnub.subscribe() and pubnub.unsubscribe() methods have been marked as deprecated but will continue to function for the documented EOL period.

For specific information about the deprecation schedule for your SDK, please refer to the documented EOL period in your SDK's documentation, typically found toward the bottom of the SDK feature list.

Status events​

When channels are subscribed, connections are disconnected, reconnected or when connection errors are encountered, status events are generated and clients can receive those events in the listener's status listener.

Listener

The status listener is the only listener that you add to the pubnub object, and not to a particular subscription or a subscription set.

Most SDKs provide an operation and category as part of a status event. The supported categories may vary with each language and platform, and some SDKs may have a more robust architecture than others. The differences will be noted as necessary.

Handle Status Events​

The event listeners are briefly mentioned in Receive Messages. Compared to other event types, status events are more focused on connection status and subscribe request errors.

Because the browser can detect when the connection is lost and restored, the JavaScript SDK (when running in a browser) has two additional events that allow you to explicitly handle those scenarios: PNNetworkDownCategory and PNNetworkUpCategory. Other environments do not support this real-time network status behavior.

The following data can be extracted from a JavaScript SDK status event.

// add a status listener
pubnub.addListener({
    status: (s) => {
      console.log('Status', s.category),
       }
});

// available data:
//     var affectedChannelGroups = event.affectedChannelGroups;
//     var affectedChannels = event.affectedChannels;
//     var category = event.category;
//     var operation = event.operation;
//     var lastTimetoken = event.lastTimetoken;
//     var currentTimetoken = event.currentTimetoken;
//     var subscribedChannels = event.subscribedChannels;

For more details on handling Status Events, visit the JavaScript SDK Status Events documentation page.

Last updated on
Related Resources
On this page