Channel metadata

Clients can optionally store channel metadata such as a channel name and description. You can also use a custom field to store additional data. Some examples of custom data include a channel's type, purpose, or owner.

Refer to Channel Metadata to learn more about working with channel metadata.

Set channel metadata

Here is a simple example of adding metadata to a channel:

JavaScript

1pubnub.objects.setChannelMetadata({
2    channel: "my_channel",
3    data: {
4        name: "main channel",
5        description: "This channel is for company wide chatter.",
6        custom: {
7            "owner": "johndoe_1"
8        }
9    }
10});

Swift

1let ch = PubNubChannelMetadataBase(
2  id: "my_channel", name: "main channel",
3  custom: ["owner": "johndoe_1"]
4)
5

6pubnub.set(channel: ch) { result in
7  switch result {
8  case let .success(channelMetadata):
9    print("The metadata for `\(channelMetadata.metadataId)`: \(channelMetadata)")
10  case let .failure(error):
11    print("Create request failed with error: \(error.localized### Description)")
12  }
13}

Objective-C

1self.client.objects().setChannelMetadata(@"my_channel")
2    .name(@"main channel")
3    .information(@"This channel is for company wide chatter.")
4    .custom(@{ @"owner": @"johndoe_1" })
5    .includeFields(PNChannelCustomField)
6    .performWithCompletion(^(PNSetChannelMetadataStatus *status) {
7      if (!status.isError) {
8          /**
9           * Channel metadata successfully has been set.
10           * Channel metadata information available here: status.data.metadata
11           */
12      } else {
13          /**
14           * Handle channel metadata update error. Check 'category' property to find out possible
15           * issue because of which request did fail.
16           *
17           * Request can be resent using: [status retry]
18           */
19      }
20    });

show all 20 lines

Java

1Map<String, Object> custom = new HashMap<>();
2custom.put("owner", "johndoe_1");
3pubnub.setChannelMetadata()
4    .channel("my_channel")
5    .name("main channel")
6    .description("This channel is for company wide chatter.")
7    .custom(custom)
8    .includeCustom(true)
9    .async(result -> { /* check result */ });

C#

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

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

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

Objective-C

1self.client.objects().channelMetadata(@"my_channel")
2    .includeFields(PNChannelCustomField)
3    .performWithCompletion(^(PNFetchChannelsMetadataResult *result, PNErrorStatus *status) {
4        if (!status.isError) {
5            /**
6             * Channel metadata successfully fetched.
7             * Channel metadata information available here: result.data.metadata
8             */
9        } else {
10            /**
11             * Handle channel metadata fetch error. Check 'category' property to find out possible
12             * issue because of which request did fail.
13             *
14             * Request can be resent using: [status retry]
15             */
16        }
17    });

show all 17 lines

Java

1pubnub.getChannelMetadata()
2    .channel("my_channel")
3    .includeCustom(true)
4    .async(result -> { /* check result */ });

C#

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

Channel events

PubNub generates channel metadata events when a user metadata is set or deleted. Clients can add Objects Listeners to receive these events.

Event	Description	Publish location
Channel Metadata Set	Channel metadata is set or updated.	These events are published on {channel}.
Channel Metadata Deleted	Channel metadata is deleted.	These events are published on {channel}.

Channel metadata set:

1{
2   "channel":"ch-1",
3   "message":{
4      "event":"set",
5      "type":"channel",
6      "data":{
7         "id":"ch-1",
8         "name":"main channel",
9         "description":"A meeting room for the team",
10         "updated":"2020-02-20T23:11:20.893755"
11      }
12   },
13   "subscription":null,
14   "timetoken":"15119446002445794"
15}

Channel metadata removed:

1{
2   "channel":"ch-1",
3   "message":{
4      "event":"deleted",
5      "type":"channel",
6      "data":{
7         "id":"ch-1",
8         "name":"main channel",
9         "description":"A meeting room for the team",
10         "updated":"2020-02-20T23:11:20.893755"
11      }
12   },
13   "subscription":null,
14   "timetoken":"15119446002445794"
15}