DOCS
Ask AI

Stop receiving messages

Showing JavaScript examples.

This guide shows you how to stop a PubNub client from receiving events on a subscription or subscription set, stop everything a client holds in one call, and remove an event listener.

  • Unsubscribe one subscription or subscription set without discarding it.
  • Stop every subscription and subscription set a client holds at once.
  • Remove an event listener without unsubscribing anything.
  • Tell a deliberate stop apart from a dropped connection in the status event.

Every call on this page needs an SDK instance with at least one active subscription or subscription set. Unsubscribing and removing a listener are two independent actions, so doing only one leaves the other half in place.

An unsubscribed object with a listener still registered receives nothing, but it fires that listener again the moment you resubscribe. A subscribed object with no listener keeps receiving events it has nothing to do with. Do both if you mean to fully stop. Refer to A listener's lifecycle is independent of its subscription's.

Unsubscribe one subscription or subscription set​

Call unsubscribe() on the Subscription or SubscriptionSet object.

1subscription.unsubscribe();
2subscriptionSet.unsubscribe();

The object and every listener still registered on it survive the call. Calling subscribe() on the same object again resumes it with no need to recreate it from the entity. Unsubscribing a SubscriptionSet stops every member at once. There's no partial unsubscribe of a set, so target the individual Subscription instead if you only want to stop one member. Refer to What subscribe and unsubscribe change.

Stop every subscription and subscription set at once​

Call unsubscribeAll() on the PubNub client. It stops every subscription and subscription set that client currently holds, regardless of which object created each one, in a single call.

1pubnub.unsubscribeAll();

Not every SDK exposes it. Objective-C, PHP, Ruby, and Unreal Engine have no unsubscribeAll() equivalent, so unsubscribe channel by channel and channel group by channel group instead. Check your platform's API reference before assuming it applies to your SDK.

Remove an event listener without unsubscribing​

Removing a listener stops your code from hearing about that event type, but it doesn't unsubscribe anything. A subscription with every listener removed still receives events. It just has nothing registered to call when one arrives. How you remove one depends on which of the two registration styles you used to add it.

A listener added as a dedicated property, such as onMessage, has no separate remove call. Setting the property to null (or your language's equivalent empty value) clears it, the same way assigning the property again replaces the previous callback:

1subscription.onMessage = null;

A listener added with the generic-listener call is removed by passing the same reference to the matching remove call on the object you added it to:

1const listener = {
2  message: (messageEvent) => { console.log('Message received:', messageEvent.message); },
3};
4

5pubnub.addListener(listener);
6// Later, stop hearing about these events without unsubscribing
7pubnub.removeListener(listener);

removeAllListeners() clears every generic listener registered on the client in one call.

An entity-based subscription's addListener() registers and removes listeners the same way the client-level call does. The same pattern applies whether you added the listener to pubnub, to a Subscription, or to a SubscriptionSet. The exact method name still varies by language, so confirm it in your SDK's API reference.

Tell a deliberate stop from a dropped connection​

Unsubscribing produces its own status event, distinct from the one a lost connection produces. The status listener reports Disconnected after your application called unsubscribe() or unsubscribeAll(). It reports Disconnected unexpectedly after a connection that was working stopped on its own and exhausted its retries.

Branch your code on which one arrived. That way it can tell "I asked for this" apart from "the network did this," instead of treating every disconnect as a failure to recover from. Refer to Subscribe lifecycle statuses for the full set of categories and to Monitor and respond to connection status changes for the listener code.

What else changes when you stop​

  • A deliberate unsubscribe reports presence sooner. When Presence is enabled, unsubscribing produces an immediate leave event instead of waiting for the server-side presence timeout to expire. Letting a client go quiet without unsubscribing leaves it looking online until that timeout passes. Refer to Leaving deliberately.
  • A channel group can remove a client without any call from that client. Because a channel group is a server-side list, removing a channel from the group your client is subscribed to stops that client from receiving it, with no unsubscribe() call on the client's side. Refer to Three ways to name what you receive.
  • The client-level subscribe() and unsubscribe() calls that predate entities are deprecated, not removed. Each SDK keeps them working for its own documented end-of-life period, so existing code that calls them keeps running, but new code should use Subscription and SubscriptionSet objects instead. The deprecation schedule itself is per SDK, listed in each platform's API reference.

Was this page useful?

Last updated on