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

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

Swift

let ch = PubNubChannelMetadataBase(
  id: "my_channel", name: "main channel",
  custom: ["owner": "johndoe_1"]
)

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

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

Java

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(result -> { /* check result */ });

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;

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

Java

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

C#

PNResult<PNGetChannelMetadataResult> getChannelMetadataResponse = await pubnub.GetChannelMetadata()
    .Channel("my_channel")
    .IncludeCustom(true)
    .ExecuteAsync();
PNGetChannelMetadataResult getChannelMetadataResult = getChannelMetadataResponse.Result;
PNStatus 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:

{
   "channel":"ch-1",
   "message":{
      "event":"set",
      "type":"channel",
      "data":{
         "id":"ch-1",
         "name":"main channel",
         "description":"A meeting room for the team",
         "updated":"2020-02-20T23:11:20.893755"
      }
   },
   "subscription":null,
   "timetoken":"15119446002445794"
}

Channel metadata removed:

{
   "channel":"ch-1",
   "message":{
      "event":"deleted",
      "type":"channel",
      "data":{
         "id":"ch-1",
         "name":"main channel",
         "description":"A meeting room for the team",
         "updated":"2020-02-20T23:11:20.893755"
      }
   },
   "subscription":null,
   "timetoken":"15119446002445794"
}