Set, get, and remove channel metadata

Showing JavaScript examples.

Starting a new app? Use DataSync

DataSync is the successor to App Context. It does everything App Context does for users, channels, and memberships, and adds typed schemas, partial updates with ETags, field-level access control, and per-class expiry. Refer to How DataSync compares to App Context for a feature-by-feature comparison.

DataSync is currently available to new accounts and to accounts that are not actively using App Context. If your keysets already use App Context, keep using it for now. App Context remains fully supported and these pages stay accurate.

This guide shows you how to give a single channel its App Context metadata: set its built-in and custom fields, read them back, and remove the whole record. App Context must be enabled on the keyset before you call it, and new keysets don't enable it by default. To read or list every channel's metadata at once instead of one channel, refer to Get metadata for all channels.

Set channel metadata

Call Set Channel Metadata with the channel's name and a data object holding the built-in name and description fields plus any custom fields your application needs. The call creates the record if it doesn't exist yet, or updates it if it does.

Unsupported partial updates of custom metadata

The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must:

1. Get the existing metadata and store it locally.
2. Append the new custom metadata to the existing one.
3. Set the entire updated custom object.

• JavaScript
• Java
• Kotlin
• C#
• Go
• Swift
• PHP
• Unity

1

If Access Manager is enabled on your keyset, this call requires an update permission grant on the channel. On success, the call also fires the set App Context event other subscribers receive.

Pass the eTag from a get call as ifMatchesEtag on a set call to apply the update only if the record hasn't changed since you read it, so a mismatch returns HTTP 412. Most SDKs document this parameter on the same method as ifMatchesEtag. Check the API reference for your platform in Available SDKs for the exact name.

Get channel metadata

Call Get Channel Metadata with the channel's name to read its current record. Most SDKs include the custom object in the response by default. Check your platform's API reference in Available SDKs to confirm.

• JavaScript
• Java
• Kotlin
• C#
• Go
• Swift
• PHP
• Unity

1

If Access Manager is enabled, this call requires a get permission grant on the channel. A channel with no metadata record yet returns a not-found error, since publishing to a channel doesn't create one.

Remove channel metadata

Call Remove Channel Metadata with the channel's name to delete its record entirely, including every custom field. There's no way to remove a single field without rewriting the record. Refer to Set channel metadata to overwrite custom with everything except the field you want gone.

• JavaScript
• Java
• Kotlin
• C#
• Go
• Swift
• PHP
• Unity

1

If Access Manager is enabled, this call requires a delete permission grant on the channel. Turning on Enforce referential integrity for memberships in the Admin Portal also deletes every membership pointing at this channel when you remove its metadata. Leaving that setting off leaves those memberships in place, pointing at a channel with no metadata record. Refer to Membership connects users and channels for the full referential-integrity behavior.

Set, get, and remove channel metadata without code

BizOps Workspace's Channel Management module performs the same three operations from the Admin Portal, with no SDK call required:

• Create channels. Set a new channel's name, description, and custom fields.
• Update channels. Change an existing channel's fields.
• Delete channels. Remove a channel's metadata, including in bulk.

A record you create, edit, or delete in BizOps Workspace is the same record your SDK calls read and write. Changes in either place are immediately visible in the other.

Related tasks

• App Context. The three entity types and how App Context relates to messages and Presence.
• Get metadata for all channels. Page through every channel's metadata instead of one.
• Set, get, and remove members. Manage this channel's user roster.
• App Context events. The set and delete event payload this operation produces.
• App Context API limits. Field-length limits for name, description, and custom.