Channel subscriptions

Users can subscribe to channels and begin listening for messages on a single socket connection. You can subscribe to a list of up to 100 channels, or use channel groups to subscribe to the list of channels in a channel group.

Subscribing to channels initiates a real-time connection with PubNub. This connection stays open as long as the user remains subscribed from a client application. Any user subscribing to a channel receives messages in under 100ms, regardless of which global region the message was published in.

Subscriptions vs memberships

A subscription isn't the same as a membership: subscriptions allow you to send and receive messages on channels, whereas memberships are metadata about the relationship between users and channels.

Subscribe to channels

The following code samples show a client subscribing to a single channel called chats.room1.

JavaScript

pubnub.subscribe({
  channels: ['ch-1'],
  withPresence: true,
});

Swift

pubnub.subscribe(to: ["ch-1"], withPresence: true
) { result in
  switch result {
  case let .success(response):
    print("Successful Response: \(response)")
  case let .failure(error):
    print("Failed Response: \(error.localizedDescription)")
  }
}

Java

pubNub.subscribe()
        .channels(Arrays.asList("ch-1"))
        .withPresence()
        .execute();

Unity

pubnub.Subscribe()
  .Channels(new List<string>() {
    "ch-1"
  })
  .WithPresence()
  .Execute();

Typically, you subscribe to channels on app load. As a user moves around in the app, they stay subscribed to their list of channels so they can continue to receive messages on all their channels.

Subscribe to channel groups

Channel groups are useful in case users in your application need to subscribe to more than 100 channels at a time. Your application can create a channel group that holds up to 2,000 channels. Each user can now subscribe to up to 10 channel groups for a total of up to 20,000 channels.

Channel Group operations

You can't publish to a Channel Group. You can only subscribe to it. To publish within Channel Group, you need to publish to each channel individually.

JavaScript

pubnub.subscribe({
  channelGroups: ["cg_user123"],
  withPresence: true
});

Swift

pubnub.subscribe(
  to: [],
  and: ["cg_user123"],
  withPresence: true
)

Objective-C

[self.pubnub subscribeToChannelGroups:@["cg_user123"] withPresence:true];

Android

pubnub.subscribe()
  .channelGroups(Arrays.asList("cg_user123"))
  .withPresence()
  .execute();

C#

pubnub.Subscribe<string>()
  .ChannelGroups(new string[] {"cg_user123"})
  .WithPresence()
  .Execute();

Python

pubnub.subscribe()\
  .channel_groups("cg_user123")\
  .with_presence()\
  .execute()

Managing channel groups

To use a Channel Group, there is just one additional step: add channels to a channel group.

Adding channels to a channel group also creates the channel group if it doesn't already exist. Your server can add 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.

JavaScript

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

Swift

pubnub.add(
  channels: ["chats.room1", "chats.room2", "alerts.system"],
  to: "cg_user123"
) { result in
  switch result {
    case let .success(response):
      print("succeeded: \(response)")

    case let .failure(error):
      print("failed: \(error.localizedDescription)")
  }
}

Objective-C

[self.pubnub addChannels: @[@"chats.room1", @"chats.room2", @"alerts.system"]
              toGroup:"cg_user123" withCompletion:^(PNAcknowledgmentStatus *status) {
    // handle success/error
}];

Android

pubnub.addChannelsToChannelGroup()
  .channelGroup("cg_user123")
  .channels(Arrays.asList("chats.room1", "chats.room2", "alerts.system"))
  .async(new PNCallback<PNChannelGroupsAddChannelResult>() {
    @Override
    public void onResponse(PNChannelGroupsAddChannelResult result, PNStatus status) {
      if (status.isError()) {
        System.out.println("failed: " + status.getMessage());
      }
      else System.out.println("succeeded");
    }
  });

C#

pubnub.AddChannelsToChannelGroup()
  .ChannelGroup("cg_user123")
  .Channels(new string[] {"chats.room1", "chats.room2", "alerts.system"})
  .Execute(new PNChannelGroupsAddChannelResultExt((result, status) => {
      // handle success/error
    }
  ));

Python

pubnub.add_channel_to_channel_group()\
  .channels(["chats.room1", "chats.room2", "alerts.system"])\
  .channel_group("cg_user123")\
  .sync()