Channel Metadata

The Objects service allows you to persist metadata about channels, channel memberships, channel members, and users. The name and description are the predefined properties for channel metadata. Additionally, there is a custom property that you can use to store any custom attribute about a channel as per your business needs.

Channel Metadata

The PubNub Objects service emits events when the metadata associated to a particular channel ID is set or deleted. Your application can receive these events in real time and dynamically react to data changes by updating the information visible on the front end of your app, for instance.

In the following sections, we're going to focus on what you can actually do with channels and their metadata.

Set Channel Metadata

You can set any of the predefined or custom channel metadata by providing the desired information as key/value pairs. The code below adds the name, description, and custom owner information to the channel my_channel.

JavaScript

pubnub.objects.setChannelMetadata({
    channel: "my_channel",
    data: {
      name: "main channel",
      description: "This channel is for company wide chatter.",
      custom: { "owner": "johndoe_1" }
    }
});

Objective-C

self.client.objects().setChannelMetadata(@"my_channel")
    .name(@"main channel")
    .information(@"This channel is for company wide chatter.")
    .custom(@{ @"owner": @"johndoe_1" })
    .includeFields(PNChannelCustomField)
    .performWithCompletion(^(PNSetChannelMetadataStatus *status) {
      if (!status.isError) {
          /**
           * Channel metadata successfully has been set.
           * Channel metadata information available here: status.data.metadata
           */
      } else {
          /**
           * Handle channel metadata update error. Check 'category' property to find out possible
           * issue because of which request did fail.

show all 20 lines

Android

Map<String, Object> custom = new HashMap<>();
custom.put("owner", "johndoe_1");
pubnub.setChannelMetadata()
    .channel("my_channel")
    .name("main channel")
    .description("This channel is for company wide chatter.")
    .custom(custom)
    .includeCustom(true)
    .async(new PNCallback<PNSetChannelMetadataResult>() {
        @Override
        public void onResponse(@Nullable final PNSetChannelMetadataResult result, @NotNull final PNStatus status) {
            if (status.isError()) {
                //handle error
            } else {
                //handle result

show all 18 lines

C#

PNResult<PNSetChannelMetadataResult> setChannelMetadataResponse = await pubnub.SetChannelMetadata()
    .Channel("my_channel")
    .Name("main channel")
    .Description("This channel is for company wide chatter.")
    .Custom(new Dictionary<string, object>() { { "owner", "johndoe_1" } })
    .IncludeCustom(true)
    .ExecuteAsync();
PNSetChannelMetadataResult setChannelMetadataResult = setChannelMetadataResponse.Result;
PNStatus status = setChannelMetadataResponse.Status;

On success, the PubNub SDK returns same metadata object along with status 200, it will also the fire objects -> channel -> set event so it can be consumed for other clients (users). Refer to Init & Add Listener section to learn more.

Get Channel Metadata

You can retrieve the metadata of a specific channel by simply providing the channel ID. You can optionally specify whether custom metadata should be included in the response. The code below returns all metadata of the channel with the ID my_channel.

JavaScript

pubnub.objects.getChannelMetadata({
        channel: "my_channel"
});

Objective-C

self.client.objects().channelMetadata(@"my_channel")
    .includeFields(PNChannelCustomField)
    .performWithCompletion(^(PNFetchChannelsMetadataResult *result, PNErrorStatus *status) {
        if (!status.isError) {
            /**
             * Channel metadata successfully fetched.
             * Channel metadata information available here: result.data.metadata
             */
        } else {
            /**
             * Handle channel metadata fetch error. Check 'category' property to find out possible
             * issue because of which request did fail.
             *
             * Request can be resent using: [status retry]
             */

show all 17 lines

Android

pubnub.getChannelMetadata()
    .channel("my_channel")
    .includeCustom(true)
    .async(new PNCallback<PNGetChannelMetadataResult>() {
        @Override
        public void onResponse(@Nullable final PNGetChannelMetadataResult result, @NotNull final PNStatus status) {
            if (status.isError()) {
                //handle error
            } else {
                //handle result
            }
        }
    });

C#

PNResult<PNGetChannelMetadataResult> getChannelMetadataResponse = await pubnub.GetChannelMetadata()
    .Channel("my_channel")
    .IncludeCustom(true)
    .ExecuteAsync();
PNGetChannelMetadataResult getChannelMetadataResult = getChannelMetadataResponse.Result;
PNStatus status = getChannelMetadataResponse.Status;

On success, the PubNub SDK returns the metadata of the specified channel along with status 200.

Get Metadata for All Channels

You can also retrieve metadata for all the channels associated with the API key. You can optionally specify whether custom metadata should be included in the response. The code below returns all predefined and custom metadata of all channels:

JavaScript

pubnub.objects.getAllChannelMetadata();

Objective-C

self.client.objects().allChannelsMetadata()
    .start(@"<next from previous request>")
    .includeFields(PNChannelCustomField)
    .performWithCompletion(^(PNFetchAllChannelsMetadataResult *result, PNErrorStatus *status) {
        if (!status.isError) {
            /**
             * Channels metadata successfully fetched.
             * Result object has following information:
             *   result.data.metadata - list of fetched channels metadata,
             *   result.data.next - cursor bookmark for fetching the next page,
             *   result.data.prev - cursor bookmark for fetching the previous page,
             *   result.data.totalCount - total number of associated channel metadata.
        } else {
            /**
             * Handle channels metadata fetch error. Check 'category' property to find out possible

show all 21 lines

Android

pubnub.getAllChannelsMetadata()
    .includeCustom(true)
    .async(new PNCallback<PNGetAllChannelsMetadataResult>() {
        @Override
        public void onResponse(@Nullable final PNGetAllChannelsMetadataResult result, @NotNull final PNStatus status) {
            if (status.isError()) {
                //handle error
            } else {
                //handle result
            }
        }
    });

C#

PNResult<PNGetAllChannelMetadataResult> getAllChannelMetadataResponse = await pubnub.GetAllChannelMetadata()
    .IncludeCustom(true)
    .ExecuteAsync();
PNGetAllChannelMetadataResult getAllChannelMetadataResult = getAllChannelMetadataResponse.Result;
PNStatus status2 = getAllChannelMetadataResponse.Status;

On success, the PubNub SDK returns a paginated list of metadata for all channels.

Remove Channel Metadata

You can remove all metadata for a single channel. The code below removes all metadata of the channel with the ID my_channel.

JavaScript

pubnub.objects.removeChannelMetadata({
    channel: "my_channel"
});

Objective-C

self.client.objects().removeChannelMetadata(@"my_channel")
    .performWithCompletion(^(PNAcknowledgmentStatus *status) {
        if (!status.isError) {
            // Channel metadata successfully removed.
        } else {
            /**
             * Handle channel metadata remove error. Check 'category' property to find out possible
             * issue because of which request did fail.
             *
             * Request can be resent using: [status retry]
             */
        }
    });

Android

pubnub.removeChannelMetadata()
    .channel("my_channel")
    .async(new PNCallback<PNRemoveChannelMetadataResult>() {
        @Override
        public void onResponse(@Nullable final PNRemoveChannelMetadataResult result, @NotNull final PNStatus status) {
            if (status.isError()) {
                //handle error
            } else {
                //handle result
            }
        }
    });

C-Sharp

PNResult<PNRemoveChannelMetadataResult> removeChannelMetadataResponse = await pubnub.RemoveChannelMetadata()
    .Channel("my_channel")
    .ExecuteAsync();
PNRemoveChannelMetadataResult removeChannelMetadataResult = removeChannelMetadataResponse.Result;
PNStatus status = removeChannelMetadataResponse.Status;

On completion, the PubNub SDK will fire the objects -> channel -> delete event so it can be consumed for other clients (users). Refer to Receive Messages to learn more.