App Context API for JavaScript SDK

LegacyNew apps should use DataSync. Existing apps can keep using App Context. Learn about DataSync

App Context lets a PubNub client for JavaScript store metadata about users and channels, and the memberships that link them, without running a database. The methods live on pubnub.objects, and the User ID parameter is named uuid.

This page describes App Context (formerly Objects v2). To upgrade from Objects v1, see the migration guide.

The methods fall into four groups:

A membership is the stored link between a user and a channel. A membership is not a subscription and delivers no messages. Membership methods start from a user and act on the channels that the user belongs to. Member methods start from a channel and act on its users. Both kinds change the same underlying membership.

PubNub publishes an App Context event when a set or delete call succeeds, and subscribed clients receive it in real time. See App Context events.

Starting a new app? Use DataSync

DataSync is the successor to App Context. It covers the same users, channels, and memberships, and adds typed schemas, JSON Patch updates with ETags, field-level projections, and per-class expiry. See the feature-by-feature comparison.

DataSync is available to new accounts and to accounts that do not use App Context. If your keysets already use App Context, keep using it for now. App Context remains supported.

Each method returns a promise. The promise resolves with the response and rejects with a PubNubError, which carries a status object. Each method also takes a callback as the last argument. With a callback, the method returns nothing and PubNub calls the callback with (status, response). All examples use async/await and let errors throw. Wrap a call in try...catch to handle a failed request.

The methods take channel and user ID strings, not SDK channel entities.

Get metadata for all users​

getAllUUIDMetadata() returns a paginated list of the user metadata objects stored in App Context, through a PubNub client for JavaScript. Each object holds the profile fields of a user and, on request, its custom data.

Required keyset configuration
To get all channel and user metadata, you must uncheck the Disallow Get All Channel Metadata and Disallow Get All User Metadata checkboxes in the App Context section of your keyset configuration in the Admin Portal.
include#
Type: object
Default: no default
The fields to add to the response.
property of include: totalCount#
Type: boolean
Default: false
Whether the response includes totalCount, the number of user metadata objects that match the request.
property of include: customFields#
Type: boolean
Default: false
Whether each user metadata object in the response includes its custom object.
filter#
Type: string
Default: no default
The filter expression. The response includes only the user metadata objects that match it. See filtering.
sort#
Type: string or object
Default: no default
The sort order of the response. Pass an object that maps property names to 'asc' or 'desc', for example { name: 'asc' }, or pass one property name to sort in ascending order. The value null selects ascending order. The sortable properties are name, email, externalId, profileUrl, type, status, updated.
limit#
Type: number
Default: 100
The maximum number of user metadata objects to return in one response. The maximum value is 100.
page#
Type: object
Default: no default
The cursor that selects the page to return. Copy it from the next or prev property of an earlier response.
property of page: next#
Type: string
Default: no default
The cursor of the next page. Pass the next value of the previous response to continue forward.
property of page: prev#
Type: string
Default: no default
The cursor of the previous page. Pass the prev value of the previous response to go back. PubNub ignores prev when you also pass next.

Returns​

The method returns a Promise that resolves to a GetAllUUIDMetadataResponse.
status#
Type: number
The HTTP status code of the response.
data#
Type: array
The user metadata objects on this page.
property of data: id#
Type: string
The ID of the user.
property of data: name#
Type: string
The display name of the user, or null when unset.
property of data: externalId#
Type: string
The ID of the user in an external system, or null when unset.
property of data: profileUrl#
Type: string
The URL of the profile picture of the user, or null when unset.
property of data: email#
Type: string
The email address of the user, or null when unset.
property of data: type#
Type: string
The type of the user, or null when unset. The SDK always requests it.
property of data: status#
Type: string
The status of the user, or null when unset. The SDK always requests it.
property of data: custom#
Type: object
The custom data of the user. The property is present only when customFields is true. The property holds null when the user has none.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the user metadata.
totalCount#
Type: number
The number of user metadata objects that match the request. The property is present only when totalCount is true.
next#
Type: string
The cursor of the next page.
prev#
Type: string
The cursor of the previous page.

Syntax

1pubnub.objects.getAllUUIDMetadata(parameters?: {
2 include?: { totalCount?: boolean, customFields?: boolean },
3 filter?: string,
4 sort?: string | object,
5 limit?: number,
6 page?: { next?: string, prev?: string }
7}): Promise<GetAllUUIDMetadataResponse>;

Get user metadata​

getUUIDMetadata() returns the metadata of one user from App Context through a PubNub client for JavaScript. The metadata holds the profile fields of the user and, on request, its custom data.

uuid#
Type: string
Default: no default
The ID of the user to get metadata for. When omitted, the SDK uses the userId of the client. An empty string fails validation, and status.message is 'uuid' cannot be empty.
include#
Type: object
Default: no default
The fields to add to the response.
property of include: customFields#
Type: boolean
Default: true
Whether the response includes the custom object of the user.

Returns​

The method returns a Promise that resolves to a GetUUIDMetadataResponse.
status#
Type: number
The HTTP status code of the response.
data#
Type: object
The user metadata object.
property of data: id#
Type: string
The ID of the user.
property of data: name#
Type: string
The display name of the user, or null when unset.
property of data: externalId#
Type: string
The ID of the user in an external system, or null when unset.
property of data: profileUrl#
Type: string
The URL of the profile picture of the user, or null when unset.
property of data: email#
Type: string
The email address of the user, or null when unset.
property of data: type#
Type: string
The type of the user, or null when unset. The SDK always requests it.
property of data: status#
Type: string
The status of the user, or null when unset. The SDK always requests it.
property of data: custom#
Type: object
The custom data of the user. The property is present only when customFields is true.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the user metadata.

Syntax

1pubnub.objects.getUUIDMetadata(parameters?: {
2 uuid?: string,
3 include?: { customFields?: boolean }
4}): Promise<GetUUIDMetadataResponse>;

Set user metadata​

setUUIDMetadata() sets the metadata of one user in App Context through a PubNub client for JavaScript and returns the stored object. The call creates the metadata when the user has none yet.

required
uuid#
Type: string
Default: no default
The ID of the user to set metadata for. When omitted, the SDK uses the userId of the client. An empty string fails validation, and status.message is 'uuid' cannot be empty.
data required#
Type: object
Default: no default
The metadata to store for the user, made of a name, an external ID, a profile URL, an email address, a type, a status and a custom object. Without data, the request fails validation and status.message is Data cannot be empty.
property of data: name#
Type: string
Default: no default
The display name of the user.
property of data: externalId#
Type: string
Default: no default
The ID of the user in an external system.
property of data: profileUrl#
Type: string
Default: no default
The URL of the profile picture of the user.
property of data: email#
Type: string
Default: no default
The email address of the user.
property of data: type#
Type: string
Default: no default
The type of the user.
property of data: status#
Type: string
Default: no default
The status of the user.
property of data: custom#
Type: object
Default: no default
The custom data of the user. A set call replaces the whole stored custom object. To add a key, get the metadata first, add the key, and set the complete object. Values can be strings, numbers, or booleans.
include#
Type: object
Default: no default
The fields to add to the response.
property of include: customFields#
Type: boolean
Default: true
Whether the response includes the custom object of the user.
ifMatchesEtag#
Type: string
Default: no default
The eTag of the user metadata that you last read. The update applies only if the stored metadata still has this eTag. Otherwise PubNub rejects the update with HTTP status 412. Get the eTag from the response of getUUIDMetadata().
API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

Returns​

The method returns a Promise that resolves to a SetUUIDMetadataResponse.Its data property holds the stored user metadata and has the same properties as the data property of the Get user metadata response.
status#
Type: number
The HTTP status code of the response.
data#
Type: object
The stored user metadata object.

Syntax

1pubnub.objects.setUUIDMetadata(parameters: {
2 uuid?: string,
3 data: {
4 name?: string,
5 externalId?: string,
6 profileUrl?: string,
7 email?: string,
8 type?: string,
9 status?: string,
10 custom?: object
11 },
12 include?: { customFields?: boolean },
13 ifMatchesEtag?: string
14}): Promise<SetUUIDMetadataResponse>;

Remove user metadata​

removeUUIDMetadata() deletes the metadata of one user from App Context through a PubNub client for JavaScript. Deleting the metadata deletes the memberships of the user only when the keyset enforces referential integrity.

uuid#
Type: string
Default: no default
The ID of the user to delete metadata for. When omitted, the SDK uses the userId of the client. An empty string fails validation, and status.message is 'uuid' cannot be empty.

Returns​

The method returns a Promise that resolves to a RemoveUUIDMetadataResponse.
status#
Type: number
The HTTP status code of the response.
data#
Type: object
An empty object.

Syntax

1pubnub.objects.removeUUIDMetadata(parameters?: {
2 uuid?: string
3}): Promise<RemoveUUIDMetadataResponse>;

Get metadata for all channels​

getAllChannelMetadata() returns a paginated list of the channel metadata objects stored in App Context, through a PubNub client for JavaScript. Each object holds the name and description of a channel and, on request, its custom data.

Required keyset configuration
To get all channel and user metadata, you must uncheck the Disallow Get All Channel Metadata and Disallow Get All User Metadata checkboxes in the App Context section of your keyset configuration in the Admin Portal.
include#
Type: object
Default: no default
The fields to add to the response.
property of include: totalCount#
Type: boolean
Default: false
Whether the response includes totalCount, the number of channel metadata objects that match the request.
property of include: customFields#
Type: boolean
Default: false
Whether each channel metadata object in the response includes its custom object.
filter#
Type: string
Default: no default
The filter expression. The response includes only the channel metadata objects that match it. See filtering.
sort#
Type: string or object
Default: no default
The sort order of the response. Pass an object that maps property names to 'asc' or 'desc', for example { name: 'asc' }, or pass one property name to sort in ascending order. The value null selects ascending order. The sortable properties are name, description, type, status, updated.
limit#
Type: number
Default: 100
The maximum number of channel metadata objects to return in one response. The maximum value is 100.
page#
Type: object
Default: no default
The cursor that selects the page to return. Copy it from the next or prev property of an earlier response.
property of page: next#
Type: string
Default: no default
The cursor of the next page. Pass the next value of the previous response to continue forward.
property of page: prev#
Type: string
Default: no default
The cursor of the previous page. Pass the prev value of the previous response to go back. PubNub ignores prev when you also pass next.

Returns​

The method returns a Promise that resolves to a GetAllChannelMetadataResponse.
status#
Type: number
The HTTP status code of the response.
data#
Type: array
The channel metadata objects on this page.
property of data: id#
Type: string
The ID of the channel.
property of data: name#
Type: string
The name of the channel, or null when unset.
property of data: description#
Type: string
The description of the channel, or null when unset.
property of data: type#
Type: string
The type of the channel, or null when unset. The SDK always requests it.
property of data: status#
Type: string
The status of the channel, or null when unset. The SDK always requests it.
property of data: custom#
Type: object
The custom data of the channel. The property is present only when customFields is true. The property holds null when the channel has none.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the channel metadata.
totalCount#
Type: number
The number of channel metadata objects that match the request. The property is present only when totalCount is true.
next#
Type: string
The cursor of the next page.
prev#
Type: string
The cursor of the previous page.

Syntax

1pubnub.objects.getAllChannelMetadata(parameters?: {
2 include?: { totalCount?: boolean, customFields?: boolean },
3 filter?: string,
4 sort?: string | object,
5 limit?: number,
6 page?: { next?: string, prev?: string }
7}): Promise<GetAllChannelMetadataResponse>;

Get channel metadata​

getChannelMetadata() returns the metadata of one channel from App Context through a PubNub client for JavaScript. The metadata holds the name and description of the channel and, on request, its custom data.

required
channel required#
Type: string
Default: no default
The ID of the channel to get metadata for. The method takes the ID string, not an SDK channel entity. Without channel, the request fails validation and status.message is Channel cannot be empty.
include#
Type: object
Default: no default
The fields to add to the response.
property of include: customFields#
Type: boolean
Default: true
Whether the response includes the custom object of the channel.

Returns​

The method returns a Promise that resolves to a GetChannelMetadataResponse.
status#
Type: number
The HTTP status code of the response.
data#
Type: object
The channel metadata object.
property of data: id#
Type: string
The ID of the channel.
property of data: name#
Type: string
The name of the channel, or null when unset.
property of data: description#
Type: string
The description of the channel, or null when unset.
property of data: type#
Type: string
The type of the channel, or null when unset. The SDK always requests it.
property of data: status#
Type: string
The status of the channel, or null when unset. The SDK always requests it.
property of data: custom#
Type: object
The custom data of the channel. The property is present only when customFields is true.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the channel metadata.

Syntax

1pubnub.objects.getChannelMetadata(parameters: {
2 channel: string,
3 include?: { customFields?: boolean }
4}): Promise<GetChannelMetadataResponse>;

Set channel metadata​

setChannelMetadata() sets the metadata of one channel in App Context through a PubNub client for JavaScript and returns the stored object. The call creates the metadata when the channel has none yet.

required
channel required#
Type: string
Default: no default
The ID of the channel to set metadata for. The method takes the ID string, not an SDK channel entity. Without channel, the request fails validation and status.message is Channel cannot be empty.
data required#
Type: object
Default: no default
The metadata to store for the channel, made of a name, a description, a type, a status and a custom object. Without data, the request fails validation and status.message is Data cannot be empty.
property of data: name#
Type: string
Default: no default
The name of the channel.
property of data: description#
Type: string
Default: no default
The description of the channel.
property of data: type#
Type: string
Default: no default
The type of the channel.
property of data: status#
Type: string
Default: no default
The status of the channel.
property of data: custom#
Type: object
Default: no default
The custom data of the channel. A set call replaces the whole stored custom object. To add a key, get the metadata first, add the key, and set the complete object. Values can be strings, numbers, or booleans.
include#
Type: object
Default: no default
The fields to add to the response.
property of include: customFields#
Type: boolean
Default: true
Whether the response includes the custom object of the channel.
ifMatchesEtag#
Type: string
Default: no default
The eTag of the channel metadata that you last read. The update applies only if the stored metadata still has this eTag. Otherwise PubNub rejects the update with HTTP status 412. Get the eTag from the response of getChannelMetadata().
API limits

To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.

Returns​

The method returns a Promise that resolves to a SetChannelMetadataResponse.Its data property holds the stored channel metadata and has the same properties as the data property of the Get channel metadata response.
status#
Type: number
The HTTP status code of the response.
data#
Type: object
The stored channel metadata object.

Syntax

1pubnub.objects.setChannelMetadata(parameters: {
2 channel: string,
3 data: {
4 name?: string,
5 description?: string,
6 type?: string,
7 status?: string,
8 custom?: object
9 },
10 include?: { customFields?: boolean },
11 ifMatchesEtag?: string
12}): Promise<SetChannelMetadataResponse>;

Remove channel metadata​

removeChannelMetadata() deletes the metadata of one channel from App Context through a PubNub client for JavaScript. Deleting the metadata deletes the memberships of the channel only when the keyset enforces referential integrity.

required
channel required#
Type: string
Default: no default
The ID of the channel to delete metadata for. The method takes the ID string, not an SDK channel entity. Without channel, the request fails validation and status.message is Channel cannot be empty.

Returns​

The method returns a Promise that resolves to a RemoveChannelMetadataResponse.
status#
Type: number
The HTTP status code of the response.
data#
Type: object
An empty object.

Syntax

1pubnub.objects.removeChannelMetadata(parameters: {
2 channel: string
3}): Promise<RemoveChannelMetadataResponse>;

Get channel memberships​

getMemberships() returns a page of the channel memberships of one user through a PubNub client for JavaScript. A membership links the user to a channel and is not a subscription.

uuid#
Type: string
Default: no default
The ID of the user to get channel memberships for. When omitted, the SDK uses the userId of the client. An empty string fails validation, and status.message is 'uuid' cannot be empty.
include#
Type: object
Default: no default
The fields to add to the response.
property of include: totalCount#
Type: boolean
Default: false
Whether the response includes totalCount, the number of memberships of the user.
property of include: customFields#
Type: boolean
Default: false
Whether each membership in the response includes its custom object.
property of include: statusField#
Type: boolean
Default: false
Whether each membership in the response includes its status field.
property of include: typeField#
Type: boolean
Default: false
Whether each membership in the response includes its type field.
property of include: channelFields#
Type: boolean
Default: false
Whether each membership includes the metadata of its channel in the channel object, such as name and description.
property of include: customChannelFields#
Type: boolean
Default: false
Whether the channel object of each membership includes the custom object of the channel.
property of include: channelStatusField#
Type: boolean
Default: false
Whether the channel object of each membership includes the status of the channel. The statusField option controls the status of the membership instead.
property of include: channelTypeField#
Type: boolean
Default: false
Whether the channel object of each membership includes the type of the channel. The typeField option controls the type of the membership instead.
filter#
Type: string
Default: no default
The filter expression. The response includes only the memberships that match it. See filtering.
sort#
Type: string or object
Default: no default
The sort order of the response. Pass an object that maps property names to 'asc' or 'desc', for example { 'channel.name': 'asc' }, or pass one property name to sort in ascending order. The value null selects ascending order. The sortable properties are channel.id, channel.name, channel.description, channel.updated, channel.status, channel.type, updated, status, type.
limit#
Type: number
Default: 100
The maximum number of memberships to return in one response. The maximum value is 100.
page#
Type: object
Default: no default
The cursor that selects the page to return. Copy it from the next or prev property of an earlier response.
property of page: next#
Type: string
Default: no default
The cursor of the next page. Pass the next value of the previous response to continue forward.
property of page: prev#
Type: string
Default: no default
The cursor of the previous page. Pass the prev value of the previous response to go back. PubNub ignores prev when you also pass next.

Returns​

The method returns a Promise that resolves to a GetMembershipsResponse.
status#
Type: number
The HTTP status code of the response.
data#
Type: array
The memberships of the user on this page.
property of data: channel#
Type: object
The channel of the membership. With channelFields set to true it holds the channel metadata, including id, name, description, updated, and eTag. Otherwise it holds the id of the channel and the channel properties that the options request.
property of data: status#
Type: string
The status of the membership. The property is present only when statusField is true.
property of data: type#
Type: string
The type of the membership. The property is present only when typeField is true.
property of data: custom#
Type: object
The custom data of the membership. The property is present only when customFields is true.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the membership.
totalCount#
Type: number
The number of memberships of the user. The property is present only when totalCount is true.
next#
Type: string
The cursor of the next page.
prev#
Type: string
The cursor of the previous page.

Syntax

1pubnub.objects.getMemberships(parameters?: {
2 uuid?: string,
3 include?: { totalCount?: boolean, customFields?: boolean, statusField?: boolean, typeField?: boolean, channelFields?: boolean, customChannelFields?: boolean, channelStatusField?: boolean, channelTypeField?: boolean },
4 filter?: string,
5 sort?: string | object,
6 limit?: number,
7 page?: { next?: string, prev?: string }
8}): Promise<GetMembershipsResponse>;

Set channel memberships​

setMemberships() sets channel memberships for one user through a PubNub client for JavaScript and returns a page of the memberships of that user.

required
uuid#
Type: string
Default: no default
The ID of the user to set channel memberships for. When omitted, the SDK uses the userId of the client. An empty string fails validation, and status.message is 'uuid' cannot be empty.
channels required#
Type: array
Default: no default
The memberships to set for the user. Each one names a channel and can carry a custom object, a type and a status. Each element is a channel ID string or an object. The object has an id and the optional custom, type, and status properties, for example { id: "my-channel-3", custom: { owner: "PubNubUser" }, type: "regular_membership", status: "active" }. An empty array fails validation, and status.message is Channels cannot be empty.
include#
Type: object
Default: no default
The fields to add to the response. The SDK always requests the membership status and the channel status and type, whatever the options.
property of include: totalCount#
Type: boolean
Default: false
Whether the response includes totalCount, the number of memberships of the user.
property of include: customFields#
Type: boolean
Default: false
Whether each membership in the response includes its custom object.
property of include: statusField#
Type: boolean
Default: false
Whether each membership in the response includes its status field.
property of include: typeField#
Type: boolean
Default: false
Whether each membership in the response includes its type field.
property of include: channelFields#
Type: boolean
Default: false
Whether each membership includes the metadata of its channel in the channel object, such as name and description.
property of include: customChannelFields#
Type: boolean
Default: false
Whether the channel object of each membership includes the custom object of the channel.
property of include: channelStatusField#
Type: boolean
Default: false
Whether the channel object of each membership includes the status of the channel. The statusField option controls the status of the membership instead.
property of include: channelTypeField#
Type: boolean
Default: false
Whether the channel object of each membership includes the type of the channel. The typeField option controls the type of the membership instead.
filter#
Type: string
Default: no default
The filter expression. The response includes only the memberships that match it. See filtering.
sort#
Type: string or object
Default: no default
The sort order of the response. Pass an object that maps property names to 'asc' or 'desc', for example { 'channel.name': 'asc' }, or pass one property name to sort in ascending order. The value null selects ascending order. The sortable properties are channel.id, channel.name, channel.description, channel.updated, channel.status, channel.type, updated, status, type.
limit#
Type: number
Default: 100
The maximum number of memberships to return in one response. The maximum value is 100.
page#
Type: object
Default: no default
The cursor that selects the page to return. Copy it from the next or prev property of an earlier response.
property of page: next#
Type: string
Default: no default
The cursor of the next page. Pass the next value of the previous response to continue forward.
property of page: prev#
Type: string
Default: no default
The cursor of the previous page. Pass the prev value of the previous response to go back. PubNub ignores prev when you also pass next.
API limits

To learn about the maximum length of parameters used to set channel membership metadata, refer to REST API docs.

Returns​

The method returns a Promise that resolves to a SetMembershipsResponse.The data property lists the memberships of the user after the change.
status#
Type: number
The HTTP status code of the response.
data#
Type: array
The memberships of the user on this page.
property of data: channel#
Type: object
The channel of the membership. With channelFields set to true it holds the channel metadata, including id, name, description, updated, and eTag. Otherwise it holds the id of the channel and the channel properties that the options request.
property of data: status#
Type: string
The status of the membership. The SDK always requests it.
property of data: type#
Type: string
The type of the membership. The property is present only when typeField is true.
property of data: custom#
Type: object
The custom data of the membership. The property is present only when customFields is true.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the membership.
totalCount#
Type: number
The number of memberships of the user. The property is present only when totalCount is true.
next#
Type: string
The cursor of the next page.
prev#
Type: string
The cursor of the previous page.

Syntax

1pubnub.objects.setMemberships(parameters: {
2 uuid?: string,
3 channels: Array<string | { id: string, type?: string, status?: string, custom?: object }>,
4 include?: { totalCount?: boolean, customFields?: boolean, statusField?: boolean, typeField?: boolean, channelFields?: boolean, customChannelFields?: boolean, channelStatusField?: boolean, channelTypeField?: boolean },
5 filter?: string,
6 sort?: string | object,
7 limit?: number,
8 page?: { next?: string, prev?: string }
9}): Promise<SetMembershipsResponse>;

Remove channel memberships​

removeMemberships() removes channel memberships from one user through a PubNub client for JavaScript and returns a page of the remaining memberships of that user.

required
uuid#
Type: string
Default: no default
The ID of the user to remove channel memberships from. When omitted, the SDK uses the userId of the client. An empty string fails validation, and status.message is 'uuid' cannot be empty.
channels required#
Type: string[]
Default: no default
The channels to remove from the memberships of the user. An empty array fails validation, and status.message is Channels cannot be empty.
include#
Type: object
Default: no default
The fields to add to the response. The SDK always requests the membership status and the channel status and type, whatever the options.
property of include: totalCount#
Type: boolean
Default: false
Whether the response includes totalCount, the number of memberships of the user.
property of include: customFields#
Type: boolean
Default: false
Whether each membership in the response includes its custom object.
property of include: statusField#
Type: boolean
Default: false
Whether each membership in the response includes its status field.
property of include: typeField#
Type: boolean
Default: false
Whether each membership in the response includes its type field.
property of include: channelFields#
Type: boolean
Default: false
Whether each membership includes the metadata of its channel in the channel object, such as name and description.
property of include: customChannelFields#
Type: boolean
Default: false
Whether the channel object of each membership includes the custom object of the channel.
property of include: channelStatusField#
Type: boolean
Default: false
Whether the channel object of each membership includes the status of the channel. The statusField option controls the status of the membership instead.
property of include: channelTypeField#
Type: boolean
Default: false
Whether the channel object of each membership includes the type of the channel. The typeField option controls the type of the membership instead.
filter#
Type: string
Default: no default
The filter expression. The response includes only the memberships that match it. See filtering.
sort#
Type: string or object
Default: no default
The sort order of the response. Pass an object that maps property names to 'asc' or 'desc', for example { 'channel.name': 'asc' }, or pass one property name to sort in ascending order. The value null selects ascending order. The sortable properties are channel.id, channel.name, channel.description, channel.updated, channel.status, channel.type, updated, status, type.
limit#
Type: number
Default: 100
The maximum number of memberships to return in one response. The maximum value is 100.
page#
Type: object
Default: no default
The cursor that selects the page to return. Copy it from the next or prev property of an earlier response.
property of page: next#
Type: string
Default: no default
The cursor of the next page. Pass the next value of the previous response to continue forward.
property of page: prev#
Type: string
Default: no default
The cursor of the previous page. Pass the prev value of the previous response to go back. PubNub ignores prev when you also pass next.

Returns​

The method returns a Promise that resolves to a RemoveMembershipsResponse.The data property lists the memberships that remain for the user.
status#
Type: number
The HTTP status code of the response.
data#
Type: array
The memberships of the user on this page.
property of data: channel#
Type: object
The channel of the membership. With channelFields set to true it holds the channel metadata, including id, name, description, updated, and eTag. Otherwise it holds the id of the channel and the channel properties that the options request.
property of data: status#
Type: string
The status of the membership. The SDK always requests it.
property of data: type#
Type: string
The type of the membership. The property is present only when typeField is true.
property of data: custom#
Type: object
The custom data of the membership. The property is present only when customFields is true.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the membership.
totalCount#
Type: number
The number of memberships of the user. The property is present only when totalCount is true.
next#
Type: string
The cursor of the next page.
prev#
Type: string
The cursor of the previous page.

Syntax

1pubnub.objects.removeMemberships(parameters: {
2 uuid?: string,
3 channels: string[],
4 include?: { totalCount?: boolean, customFields?: boolean, statusField?: boolean, typeField?: boolean, channelFields?: boolean, customChannelFields?: boolean, channelStatusField?: boolean, channelTypeField?: boolean },
5 filter?: string,
6 sort?: string | object,
7 limit?: number,
8 page?: { next?: string, prev?: string }
9}): Promise<RemoveMembershipsResponse>;

Get channel members​

getChannelMembers() returns a page of the members of one channel through a PubNub client for JavaScript. A member is a user that has a membership in the channel.

required
channel required#
Type: string
Default: no default
The ID of the channel to get members for. The method takes the ID string, not an SDK channel entity. Without channel, the request fails validation and status.message is Channel cannot be empty.
include#
Type: object
Default: no default
The fields to add to the response.
property of include: totalCount#
Type: boolean
Default: false
Whether the response includes totalCount, the number of members of the channel.
property of include: customFields#
Type: boolean
Default: false
Whether each member in the response includes its custom object.
property of include: statusField#
Type: boolean
Default: false
Whether each member in the response includes its status field.
property of include: typeField#
Type: boolean
Default: false
Whether each member in the response includes its type field.
property of include: UUIDFields#
Type: boolean
Default: false
Whether each member includes the metadata of its user in the uuid object, such as name and email.
property of include: customUUIDFields#
Type: boolean
Default: false
Whether the uuid object of each member includes the custom object of the user.
property of include: UUIDStatusField#
Type: boolean
Default: false
Whether the uuid object of each member includes the status of the user. The statusField option controls the status of the member instead.
property of include: UUIDTypeField#
Type: boolean
Default: false
Whether the uuid object of each member includes the type of the user. The typeField option controls the type of the member instead.
filter#
Type: string
Default: no default
The filter expression. The response includes only the members that match it. See filtering.
sort#
Type: string or object
Default: no default
The sort order of the response. Pass an object that maps property names to 'asc' or 'desc', for example { 'uuid.name': 'asc' }, or pass one property name to sort in ascending order. The value null selects ascending order. The sortable properties are uuid.id, uuid.name, uuid.updated, uuid.status, uuid.type, updated, status, type.
limit#
Type: number
Default: 100
The maximum number of members to return in one response. The maximum value is 100.
page#
Type: object
Default: no default
The cursor that selects the page to return. Copy it from the next or prev property of an earlier response.
property of page: next#
Type: string
Default: no default
The cursor of the next page. Pass the next value of the previous response to continue forward.
property of page: prev#
Type: string
Default: no default
The cursor of the previous page. Pass the prev value of the previous response to go back. PubNub ignores prev when you also pass next.

Returns​

The method returns a Promise that resolves to a GetMembersResponse.
status#
Type: number
The HTTP status code of the response.
data#
Type: array
The members of the channel on this page.
property of data: uuid#
Type: object
The user of the member. With UUIDFields set to true it holds the user metadata, including id, name, email, updated, and eTag. Otherwise it holds the id of the user and the user properties that the options request.
property of data: status#
Type: string
The status of the member. The property is present only when statusField is true.
property of data: type#
Type: string
The type of the member. The property is present only when typeField is true.
property of data: custom#
Type: object
The custom data of the member. The property is present only when customFields is true.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the member.
totalCount#
Type: number
The number of members of the channel. The property is present only when totalCount is true.
next#
Type: string
The cursor of the next page.
prev#
Type: string
The cursor of the previous page.

Syntax

1pubnub.objects.getChannelMembers(parameters: {
2 channel: string,
3 include?: { totalCount?: boolean, customFields?: boolean, statusField?: boolean, typeField?: boolean, UUIDFields?: boolean, customUUIDFields?: boolean, UUIDStatusField?: boolean, UUIDTypeField?: boolean },
4 filter?: string,
5 sort?: string | object,
6 limit?: number,
7 page?: { next?: string, prev?: string }
8}): Promise<GetMembersResponse>;

Set channel members​

setChannelMembers() sets members for one channel through a PubNub client for JavaScript and returns a page of the members of that channel.

required
channel required#
Type: string
Default: no default
The ID of the channel to set members for. The method takes the ID string, not an SDK channel entity. Without channel, the request fails validation and status.message is Channel cannot be empty.
uuids required#
Type: array
Default: no default
The members to set for the channel. Each one names a user and can carry a custom object, a type and a status. Each element is a user ID string or an object. The object has an id and the optional custom, type, and status properties, for example { id: "uuid-3", custom: { role: "Super Admin" } }. An empty array fails validation, and status.message is UUIDs cannot be empty.
include#
Type: object
Default: no default
The fields to add to the response. The SDK always requests the member type and the user status and type, whatever the options.
property of include: totalCount#
Type: boolean
Default: false
Whether the response includes totalCount, the number of members of the channel.
property of include: customFields#
Type: boolean
Default: false
Whether each member in the response includes its custom object.
property of include: statusField#
Type: boolean
Default: false
Whether each member in the response includes its status field.
property of include: typeField#
Type: boolean
Default: false
Whether each member in the response includes its type field.
property of include: UUIDFields#
Type: boolean
Default: false
Whether each member includes the metadata of its user in the uuid object, such as name and email.
property of include: customUUIDFields#
Type: boolean
Default: false
Whether the uuid object of each member includes the custom object of the user.
property of include: UUIDStatusField#
Type: boolean
Default: false
Whether the uuid object of each member includes the status of the user. The statusField option controls the status of the member instead.
property of include: UUIDTypeField#
Type: boolean
Default: false
Whether the uuid object of each member includes the type of the user. The typeField option controls the type of the member instead.
filter#
Type: string
Default: no default
The filter expression. The response includes only the members that match it. See filtering.
sort#
Type: string or object
Default: no default
The sort order of the response. Pass an object that maps property names to 'asc' or 'desc', for example { 'uuid.name': 'asc' }, or pass one property name to sort in ascending order. The value null selects ascending order. The sortable properties are uuid.id, uuid.name, uuid.updated, uuid.status, uuid.type, updated, status, type.
limit#
Type: number
Default: 100
The maximum number of members to return in one response. The maximum value is 100.
page#
Type: object
Default: no default
The cursor that selects the page to return. Copy it from the next or prev property of an earlier response.
property of page: next#
Type: string
Default: no default
The cursor of the next page. Pass the next value of the previous response to continue forward.
property of page: prev#
Type: string
Default: no default
The cursor of the previous page. Pass the prev value of the previous response to go back. PubNub ignores prev when you also pass next.
API limits

To learn about the maximum length of parameters used to set channel members metadata, refer to REST API docs.

Returns​

The method returns a Promise that resolves to a SetMembersResponse.The data property lists the members of the channel after the change.
status#
Type: number
The HTTP status code of the response.
data#
Type: array
The members of the channel on this page.
property of data: uuid#
Type: object
The user of the member. With UUIDFields set to true it holds the user metadata, including id, name, email, updated, and eTag. Otherwise it holds the id of the user and the user properties that the options request.
property of data: status#
Type: string
The status of the member. The property is present only when statusField is true.
property of data: type#
Type: string
The type of the member. The SDK always requests it.
property of data: custom#
Type: object
The custom data of the member. The property is present only when customFields is true.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the member.
totalCount#
Type: number
The number of members of the channel. The property is present only when totalCount is true.
next#
Type: string
The cursor of the next page.
prev#
Type: string
The cursor of the previous page.

Syntax

1pubnub.objects.setChannelMembers(parameters: {
2 channel: string,
3 uuids: Array<string | { id: string, type?: string, status?: string, custom?: object }>,
4 include?: { totalCount?: boolean, customFields?: boolean, statusField?: boolean, typeField?: boolean, UUIDFields?: boolean, customUUIDFields?: boolean, UUIDStatusField?: boolean, UUIDTypeField?: boolean },
5 filter?: string,
6 sort?: string | object,
7 limit?: number,
8 page?: { next?: string, prev?: string }
9}): Promise<SetMembersResponse>;

Remove channel members​

removeChannelMembers() removes members from one channel through a PubNub client for JavaScript and returns a page of the remaining members of that channel.

required
channel required#
Type: string
Default: no default
The ID of the channel to remove members from. The method takes the ID string, not an SDK channel entity. Without channel, the request fails validation and status.message is Channel cannot be empty.
uuids required#
Type: string[]
Default: no default
The users to remove from the members of the channel. An empty array fails validation, and status.message is UUIDs cannot be empty.
include#
Type: object
Default: no default
The fields to add to the response. The SDK always requests the member type and the user status and type, whatever the options.
property of include: totalCount#
Type: boolean
Default: false
Whether the response includes totalCount, the number of members of the channel.
property of include: customFields#
Type: boolean
Default: false
Whether each member in the response includes its custom object.
property of include: statusField#
Type: boolean
Default: false
Whether each member in the response includes its status field.
property of include: typeField#
Type: boolean
Default: false
Whether each member in the response includes its type field.
property of include: UUIDFields#
Type: boolean
Default: false
Whether each member includes the metadata of its user in the uuid object, such as name and email.
property of include: customUUIDFields#
Type: boolean
Default: false
Whether the uuid object of each member includes the custom object of the user.
property of include: UUIDStatusField#
Type: boolean
Default: false
Whether the uuid object of each member includes the status of the user. The statusField option controls the status of the member instead.
property of include: UUIDTypeField#
Type: boolean
Default: false
Whether the uuid object of each member includes the type of the user. The typeField option controls the type of the member instead.
filter#
Type: string
Default: no default
The filter expression. The response includes only the members that match it. See filtering.
sort#
Type: string or object
Default: no default
The sort order of the response. Pass an object that maps property names to 'asc' or 'desc', for example { 'uuid.name': 'asc' }, or pass one property name to sort in ascending order. The value null selects ascending order. The sortable properties are uuid.id, uuid.name, uuid.updated, uuid.status, uuid.type, updated, status, type.
limit#
Type: number
Default: 100
The maximum number of members to return in one response. The maximum value is 100.
page#
Type: object
Default: no default
The cursor that selects the page to return. Copy it from the next or prev property of an earlier response.
property of page: next#
Type: string
Default: no default
The cursor of the next page. Pass the next value of the previous response to continue forward.
property of page: prev#
Type: string
Default: no default
The cursor of the previous page. Pass the prev value of the previous response to go back. PubNub ignores prev when you also pass next.

Returns​

The method returns a Promise that resolves to a RemoveMembersResponse.The data property lists the members that remain in the channel.
status#
Type: number
The HTTP status code of the response.
data#
Type: array
The members of the channel on this page.
property of data: uuid#
Type: object
The user of the member. With UUIDFields set to true it holds the user metadata, including id, name, email, updated, and eTag. Otherwise it holds the id of the user and the user properties that the options request.
property of data: status#
Type: string
The status of the member. The property is present only when statusField is true.
property of data: type#
Type: string
The type of the member. The SDK always requests it.
property of data: custom#
Type: object
The custom data of the member. The property is present only when customFields is true.
property of data: updated#
Type: string
The date and time of the last update, in ISO 8601 format.
property of data: eTag#
Type: string
The version hash of the member.
totalCount#
Type: number
The number of members of the channel. The property is present only when totalCount is true.
next#
Type: string
The cursor of the next page.
prev#
Type: string
The cursor of the previous page.

Syntax

1pubnub.objects.removeChannelMembers(parameters: {
2 channel: string,
3 uuids: string[],
4 include?: { totalCount?: boolean, customFields?: boolean, statusField?: boolean, typeField?: boolean, UUIDFields?: boolean, customUUIDFields?: boolean, UUIDStatusField?: boolean, UUIDTypeField?: boolean },
5 filter?: string,
6 sort?: string | object,
7 limit?: number,
8 page?: { next?: string, prev?: string }
9}): Promise<RemoveMembersResponse>;

Was this page useful?

Last updated on