App Context API for JavaScript SDK
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:
- User metadata: Get metadata for all users, Get user metadata, Set user metadata, and Remove user metadata.
- Channel metadata: Get metadata for all channels, Get channel metadata, Set channel metadata, and Remove channel metadata.
- Channel memberships: Get channel memberships, Set channel memberships, and Remove channel memberships.
- Channel members: Get channel members, Set channel members, and Remove channel members.
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
include#- The fields to add to the response.
- property of include:
totalCount# - Whether the response includes
totalCount, the number of user metadata objects that match the request. - property of include:
customFields# - Whether each user metadata object in the response includes its
customobject. filter#- The filter expression. The response includes only the user metadata objects that match it. See filtering.
sort#- 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 valuenullselects ascending order. The sortable properties arename, email, externalId, profileUrl, type, status, updated. limit#- The maximum number of user metadata objects to return in one response. The maximum value is
100. page#- The cursor that selects the page to return. Copy it from the
nextorprevproperty of an earlier response. - property of page:
next# - The cursor of the next page. Pass the
nextvalue of the previous response to continue forward. - property of page:
prev# - The cursor of the previous page. Pass the
prevvalue of the previous response to go back. PubNub ignoresprevwhen you also passnext.
Sample code
Returns
The method returns aPromise that resolves to a GetAllUUIDMetadataResponse.status#- The HTTP status code of the response.
data#- The user metadata objects on this page.
- property of data:
id# - The ID of the user.
- property of data:
name# - The display name of the user, or
nullwhen unset. - property of data:
externalId# - The ID of the user in an external system, or
nullwhen unset. - property of data:
profileUrl# - The URL of the profile picture of the user, or
nullwhen unset. - property of data:
email# - The email address of the user, or
nullwhen unset. - property of data:
type# - The type of the user, or
nullwhen unset. The SDK always requests it. - property of data:
status# - The status of the user, or
nullwhen unset. The SDK always requests it. - property of data:
custom# - The custom data of the user. The property is present only when
customFieldsistrue. The property holdsnullwhen the user has none. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the user metadata.
totalCount#- The number of user metadata objects that match the request. The property is present only when
totalCountistrue. next#- The cursor of the next page.
prev#- The cursor of the previous page.
Examples for Get metadata for all users
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>;
Basic usage
1
1
Returns
1{
2 "status": 200,
3 "data": [
4 {
5 "id": "uuid-1",
6 "name": "John Doe",
7 "externalId": null,
8 "profileUrl": null,
9 "email": "johndoe@pubnub.com",
10 "custom": null,
11 "updated": "2019-02-20T23:11:20.893755",
12 "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
13 },
14 {
15 "id": "uuid-2",
show all 27 linesGet 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#- The ID of the user to get metadata for. When omitted, the SDK uses the
userIdof the client. An empty string fails validation, andstatus.messageis'uuid' cannot be empty. include#- The fields to add to the response.
- property of include:
customFields# - Whether the response includes the
customobject of the user.
Sample code
Returns
The method returns aPromise that resolves to a GetUUIDMetadataResponse.status#- The HTTP status code of the response.
data#- The user metadata object.
- property of data:
id# - The ID of the user.
- property of data:
name# - The display name of the user, or
nullwhen unset. - property of data:
externalId# - The ID of the user in an external system, or
nullwhen unset. - property of data:
profileUrl# - The URL of the profile picture of the user, or
nullwhen unset. - property of data:
email# - The email address of the user, or
nullwhen unset. - property of data:
type# - The type of the user, or
nullwhen unset. The SDK always requests it. - property of data:
status# - The status of the user, or
nullwhen unset. The SDK always requests it. - property of data:
custom# - The custom data of the user. The property is present only when
customFieldsistrue. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the user metadata.
Examples for Get user metadata
Syntax
1pubnub.objects.getUUIDMetadata(parameters?: {
2 uuid?: string,
3 include?: { customFields?: boolean }
4}): Promise<GetUUIDMetadataResponse>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": {
4 "id": "uuid-1",
5 "name": "John Doe",
6 "externalId": null,
7 "profileUrl": null,
8 "email": "johndoe@pubnub.com",
9 "updated": "2019-02-20T23:11:20.893755",
10 "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
11 }
12}
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.
uuid#- The ID of the user to set metadata for. When omitted, the SDK uses the
userIdof the client. An empty string fails validation, andstatus.messageis'uuid' cannot be empty. datarequired#- 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 andstatus.messageisData cannot be empty. - property of data:
name# - The display name of the user.
- property of data:
externalId# - The ID of the user in an external system.
- property of data:
profileUrl# - The URL of the profile picture of the user.
- property of data:
email# - The email address of the user.
- property of data:
type# - The type of the user.
- property of data:
status# - The status of the user.
- property of data:
custom# - The custom data of the user. A set call replaces the whole stored
customobject. To add a key, get the metadata first, add the key, and set the complete object. Values can be strings, numbers, or booleans. include#- The fields to add to the response.
- property of include:
customFields# - Whether the response includes the
customobject of the user. ifMatchesEtag#- The
eTagof the user metadata that you last read. The update applies only if the stored metadata still has thiseTag. Otherwise PubNub rejects the update with HTTP status 412. Get theeTagfrom the response ofgetUUIDMetadata().
API limits
To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.
Sample code
Returns
The method returns aPromise 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.Examples for Set user metadata
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>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": {
4 "id": "uuid-1",
5 "name": "John Doe",
6 "externalId": null,
7 "profileUrl": null,
8 "email": "johndoe@pubnub.com",
9 "updated": "2019-02-20T23:11:20.893755",
10 "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
11 }
12}
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#- The ID of the user to delete metadata for. When omitted, the SDK uses the
userIdof the client. An empty string fails validation, andstatus.messageis'uuid' cannot be empty.
Sample code
Returns
The method returns aPromise that resolves to a RemoveUUIDMetadataResponse.Examples for Remove user metadata
Syntax
1pubnub.objects.removeUUIDMetadata(parameters?: {
2 uuid?: string
3}): Promise<RemoveUUIDMetadataResponse>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": {}
4}
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
include#- The fields to add to the response.
- property of include:
totalCount# - Whether the response includes
totalCount, the number of channel metadata objects that match the request. - property of include:
customFields# - Whether each channel metadata object in the response includes its
customobject. filter#- The filter expression. The response includes only the channel metadata objects that match it. See filtering.
sort#- 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 valuenullselects ascending order. The sortable properties arename, description, type, status, updated. limit#- The maximum number of channel metadata objects to return in one response. The maximum value is
100. page#- The cursor that selects the page to return. Copy it from the
nextorprevproperty of an earlier response. - property of page:
next# - The cursor of the next page. Pass the
nextvalue of the previous response to continue forward. - property of page:
prev# - The cursor of the previous page. Pass the
prevvalue of the previous response to go back. PubNub ignoresprevwhen you also passnext.
Sample code
Returns
The method returns aPromise that resolves to a GetAllChannelMetadataResponse.status#- The HTTP status code of the response.
data#- The channel metadata objects on this page.
- property of data:
id# - The ID of the channel.
- property of data:
name# - The name of the channel, or
nullwhen unset. - property of data:
description# - The description of the channel, or
nullwhen unset. - property of data:
type# - The type of the channel, or
nullwhen unset. The SDK always requests it. - property of data:
status# - The status of the channel, or
nullwhen unset. The SDK always requests it. - property of data:
custom# - The custom data of the channel. The property is present only when
customFieldsistrue. The property holdsnullwhen the channel has none. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the channel metadata.
totalCount#- The number of channel metadata objects that match the request. The property is present only when
totalCountistrue. next#- The cursor of the next page.
prev#- The cursor of the previous page.
Examples for Get metadata for all channels
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>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": [
4 {
5 "id": "team.blue",
6 "name": "Blue Team",
7 "description": "The channel for Blue team and no other teams.",
8 "custom": null,
9 "updated": "2019-02-20T23:11:20.893755",
10 "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
11 },
12 {
13 "id": "team.red",
14 "name": "Red Team",
15 "description": "The channel for Red team and no other teams.",
show all 35 linesGet 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.
channelrequired#- 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 andstatus.messageisChannel cannot be empty. include#- The fields to add to the response.
- property of include:
customFields# - Whether the response includes the
customobject of the channel.
Sample code
Returns
The method returns aPromise that resolves to a GetChannelMetadataResponse.status#- The HTTP status code of the response.
data#- The channel metadata object.
- property of data:
id# - The ID of the channel.
- property of data:
name# - The name of the channel, or
nullwhen unset. - property of data:
description# - The description of the channel, or
nullwhen unset. - property of data:
type# - The type of the channel, or
nullwhen unset. The SDK always requests it. - property of data:
status# - The status of the channel, or
nullwhen unset. The SDK always requests it. - property of data:
custom# - The custom data of the channel. The property is present only when
customFieldsistrue. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the channel metadata.
Examples for Get channel metadata
Syntax
1pubnub.objects.getChannelMetadata(parameters: {
2 channel: string,
3 include?: { customFields?: boolean }
4}): Promise<GetChannelMetadataResponse>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": {
4 "id": "team.blue",
5 "name": "Blue Team",
6 "description": "The channel for Blue team and no other teams.",
7 "updated": "2019-02-20T23:11:20.893755",
8 "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
9 }
10}
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.
channelrequired#- 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 andstatus.messageisChannel cannot be empty. datarequired#- 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 andstatus.messageisData cannot be empty. - property of data:
name# - The name of the channel.
- property of data:
description# - The description of the channel.
- property of data:
type# - The type of the channel.
- property of data:
status# - The status of the channel.
- property of data:
custom# - The custom data of the channel. A set call replaces the whole stored
customobject. To add a key, get the metadata first, add the key, and set the complete object. Values can be strings, numbers, or booleans. include#- The fields to add to the response.
- property of include:
customFields# - Whether the response includes the
customobject of the channel. ifMatchesEtag#- The
eTagof the channel metadata that you last read. The update applies only if the stored metadata still has thiseTag. Otherwise PubNub rejects the update with HTTP status 412. Get theeTagfrom the response ofgetChannelMetadata().
API limits
To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.
Sample code
Returns
The method returns aPromise 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.Other examples
Examples for Set channel metadata
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>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": {
4 "id": "team.red",
5 "name": "Red Team",
6 "description": "The channel for Blue team and no other teams.",
7 "updated": "2019-02-20T23:11:20.893755",
8 "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
9 }
10}
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.
channelrequired#- 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 andstatus.messageisChannel cannot be empty.
Sample code
Returns
The method returns aPromise that resolves to a RemoveChannelMetadataResponse.Examples for Remove channel metadata
Syntax
1pubnub.objects.removeChannelMetadata(parameters: {
2 channel: string
3}): Promise<RemoveChannelMetadataResponse>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": {}
4}
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#- The ID of the user to get channel memberships for. When omitted, the SDK uses the
userIdof the client. An empty string fails validation, andstatus.messageis'uuid' cannot be empty. include#- The fields to add to the response.
- property of include:
totalCount# - Whether the response includes
totalCount, the number of memberships of the user. - property of include:
customFields# - Whether each membership in the response includes its
customobject. - property of include:
statusField# - Whether each membership in the response includes its
statusfield. - property of include:
typeField# - Whether each membership in the response includes its
typefield. - property of include:
channelFields# - Whether each membership includes the metadata of its channel in the
channelobject, such asnameanddescription. - property of include:
customChannelFields# - Whether the
channelobject of each membership includes thecustomobject of the channel. - property of include:
channelStatusField# - Whether the
channelobject of each membership includes thestatusof the channel. ThestatusFieldoption controls thestatusof the membership instead. - property of include:
channelTypeField# - Whether the
channelobject of each membership includes thetypeof the channel. ThetypeFieldoption controls thetypeof the membership instead. filter#- The filter expression. The response includes only the memberships that match it. See filtering.
sort#- 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 valuenullselects ascending order. The sortable properties arechannel.id, channel.name, channel.description, channel.updated, channel.status, channel.type, updated, status, type. limit#- The maximum number of memberships to return in one response. The maximum value is
100. page#- The cursor that selects the page to return. Copy it from the
nextorprevproperty of an earlier response. - property of page:
next# - The cursor of the next page. Pass the
nextvalue of the previous response to continue forward. - property of page:
prev# - The cursor of the previous page. Pass the
prevvalue of the previous response to go back. PubNub ignoresprevwhen you also passnext.
Sample code
Returns
The method returns aPromise that resolves to a GetMembershipsResponse.status#- The HTTP status code of the response.
data#- The memberships of the user on this page.
- property of data:
channel# - The channel of the membership. With
channelFieldsset totrueit holds the channel metadata, includingid,name,description,updated, andeTag. Otherwise it holds theidof the channel and the channel properties that the options request. - property of data:
status# - The status of the membership. The property is present only when
statusFieldistrue. - property of data:
type# - The type of the membership. The property is present only when
typeFieldistrue. - property of data:
custom# - The custom data of the membership. The property is present only when
customFieldsistrue. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the membership.
totalCount#- The number of memberships of the user. The property is present only when
totalCountistrue. next#- The cursor of the next page.
prev#- The cursor of the previous page.
Examples for Get channel memberships
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>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": [
4 {
5 "channel": {
6 "id": "my-channel",
7 "name": "My channel",
8 "description": "A channel that is mine",
9 "custom": null,
10 "updated": "2019-02-20T23:11:20.893755",
11 "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
12 },
13 "custom": {
14 "starred": false
15 },
show all 38 linesSet 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.
uuid#- The ID of the user to set channel memberships for. When omitted, the SDK uses the
userIdof the client. An empty string fails validation, andstatus.messageis'uuid' cannot be empty. channelsrequired#- 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
idand the optionalcustom,type, andstatusproperties, for example{ id: "my-channel-3", custom: { owner: "PubNubUser" }, type: "regular_membership", status: "active" }. An empty array fails validation, andstatus.messageisChannels cannot be empty. include#- 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# - Whether the response includes
totalCount, the number of memberships of the user. - property of include:
customFields# - Whether each membership in the response includes its
customobject. - property of include:
statusField# - Whether each membership in the response includes its
statusfield. - property of include:
typeField# - Whether each membership in the response includes its
typefield. - property of include:
channelFields# - Whether each membership includes the metadata of its channel in the
channelobject, such asnameanddescription. - property of include:
customChannelFields# - Whether the
channelobject of each membership includes thecustomobject of the channel. - property of include:
channelStatusField# - Whether the
channelobject of each membership includes thestatusof the channel. ThestatusFieldoption controls thestatusof the membership instead. - property of include:
channelTypeField# - Whether the
channelobject of each membership includes thetypeof the channel. ThetypeFieldoption controls thetypeof the membership instead. filter#- The filter expression. The response includes only the memberships that match it. See filtering.
sort#- 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 valuenullselects ascending order. The sortable properties arechannel.id, channel.name, channel.description, channel.updated, channel.status, channel.type, updated, status, type. limit#- The maximum number of memberships to return in one response. The maximum value is
100. page#- The cursor that selects the page to return. Copy it from the
nextorprevproperty of an earlier response. - property of page:
next# - The cursor of the next page. Pass the
nextvalue of the previous response to continue forward. - property of page:
prev# - The cursor of the previous page. Pass the
prevvalue of the previous response to go back. PubNub ignoresprevwhen you also passnext.
API limits
To learn about the maximum length of parameters used to set channel membership metadata, refer to REST API docs.
Sample code
Returns
The method returns aPromise that resolves to a SetMembershipsResponse.The data property lists the memberships of the user after the change.status#- The HTTP status code of the response.
data#- The memberships of the user on this page.
- property of data:
channel# - The channel of the membership. With
channelFieldsset totrueit holds the channel metadata, includingid,name,description,updated, andeTag. Otherwise it holds theidof the channel and the channel properties that the options request. - property of data:
status# - The status of the membership. The SDK always requests it.
- property of data:
type# - The type of the membership. The property is present only when
typeFieldistrue. - property of data:
custom# - The custom data of the membership. The property is present only when
customFieldsistrue. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the membership.
totalCount#- The number of memberships of the user. The property is present only when
totalCountistrue. next#- The cursor of the next page.
prev#- The cursor of the previous page.
Examples for Set channel memberships
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>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": [
4 {
5 "channel": {
6 "id": "my-channel",
7 "name": "My channel",
8 "description": "A channel that is mine",
9 "custom": null,
10 "updated": "2019-02-20T23:11:20.893755",
11 "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
12 },
13 "custom": {
14 "starred": false
15 },
show all 38 linesRemove 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.
uuid#- The ID of the user to remove channel memberships from. When omitted, the SDK uses the
userIdof the client. An empty string fails validation, andstatus.messageis'uuid' cannot be empty. channelsrequired#- The channels to remove from the memberships of the user. An empty array fails validation, and
status.messageisChannels cannot be empty. include#- 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# - Whether the response includes
totalCount, the number of memberships of the user. - property of include:
customFields# - Whether each membership in the response includes its
customobject. - property of include:
statusField# - Whether each membership in the response includes its
statusfield. - property of include:
typeField# - Whether each membership in the response includes its
typefield. - property of include:
channelFields# - Whether each membership includes the metadata of its channel in the
channelobject, such asnameanddescription. - property of include:
customChannelFields# - Whether the
channelobject of each membership includes thecustomobject of the channel. - property of include:
channelStatusField# - Whether the
channelobject of each membership includes thestatusof the channel. ThestatusFieldoption controls thestatusof the membership instead. - property of include:
channelTypeField# - Whether the
channelobject of each membership includes thetypeof the channel. ThetypeFieldoption controls thetypeof the membership instead. filter#- The filter expression. The response includes only the memberships that match it. See filtering.
sort#- 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 valuenullselects ascending order. The sortable properties arechannel.id, channel.name, channel.description, channel.updated, channel.status, channel.type, updated, status, type. limit#- The maximum number of memberships to return in one response. The maximum value is
100. page#- The cursor that selects the page to return. Copy it from the
nextorprevproperty of an earlier response. - property of page:
next# - The cursor of the next page. Pass the
nextvalue of the previous response to continue forward. - property of page:
prev# - The cursor of the previous page. Pass the
prevvalue of the previous response to go back. PubNub ignoresprevwhen you also passnext.
Sample code
Returns
The method returns aPromise that resolves to a RemoveMembershipsResponse.The data property lists the memberships that remain for the user.status#- The HTTP status code of the response.
data#- The memberships of the user on this page.
- property of data:
channel# - The channel of the membership. With
channelFieldsset totrueit holds the channel metadata, includingid,name,description,updated, andeTag. Otherwise it holds theidof the channel and the channel properties that the options request. - property of data:
status# - The status of the membership. The SDK always requests it.
- property of data:
type# - The type of the membership. The property is present only when
typeFieldistrue. - property of data:
custom# - The custom data of the membership. The property is present only when
customFieldsistrue. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the membership.
totalCount#- The number of memberships of the user. The property is present only when
totalCountistrue. next#- The cursor of the next page.
prev#- The cursor of the previous page.
Examples for Remove channel memberships
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>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": [
4 {
5 "channel": {
6 "id": "my-channel",
7 "name": "My channel",
8 "description": "A channel that is mine",
9 "custom": null,
10 "updated": "2019-02-20T23:11:20.893755",
11 "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
12 },
13 "custom": {
14 "starred": false
15 },
show all 38 linesGet 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.
channelrequired#- 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 andstatus.messageisChannel cannot be empty. include#- The fields to add to the response.
- property of include:
totalCount# - Whether the response includes
totalCount, the number of members of the channel. - property of include:
customFields# - Whether each member in the response includes its
customobject. - property of include:
statusField# - Whether each member in the response includes its
statusfield. - property of include:
typeField# - Whether each member in the response includes its
typefield. - property of include:
UUIDFields# - Whether each member includes the metadata of its user in the
uuidobject, such asnameandemail. - property of include:
customUUIDFields# - Whether the
uuidobject of each member includes thecustomobject of the user. - property of include:
UUIDStatusField# - Whether the
uuidobject of each member includes thestatusof the user. ThestatusFieldoption controls thestatusof the member instead. - property of include:
UUIDTypeField# - Whether the
uuidobject of each member includes thetypeof the user. ThetypeFieldoption controls thetypeof the member instead. sort#- 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 valuenullselects ascending order. The sortable properties areuuid.id, uuid.name, uuid.updated, uuid.status, uuid.type, updated, status, type. limit#- The maximum number of members to return in one response. The maximum value is
100. page#- The cursor that selects the page to return. Copy it from the
nextorprevproperty of an earlier response. - property of page:
next# - The cursor of the next page. Pass the
nextvalue of the previous response to continue forward. - property of page:
prev# - The cursor of the previous page. Pass the
prevvalue of the previous response to go back. PubNub ignoresprevwhen you also passnext.
Sample code
Returns
The method returns aPromise that resolves to a GetMembersResponse.status#- The HTTP status code of the response.
data#- The members of the channel on this page.
- property of data:
uuid# - The user of the member. With
UUIDFieldsset totrueit holds the user metadata, includingid,name,email,updated, andeTag. Otherwise it holds theidof the user and the user properties that the options request. - property of data:
status# - The status of the member. The property is present only when
statusFieldistrue. - property of data:
type# - The type of the member. The property is present only when
typeFieldistrue. - property of data:
custom# - The custom data of the member. The property is present only when
customFieldsistrue. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the member.
totalCount#- The number of members of the channel. The property is present only when
totalCountistrue. next#- The cursor of the next page.
prev#- The cursor of the previous page.
Examples for Get channel members
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>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": [
4 {
5 "uuid": {
6 "id": "uuid-1",
7 "name": "John Doe",
8 "externalId": null,
9 "profileUrl": null,
10 "email": "jack@twitter.com",
11 "custom": null,
12 "updated": "2019-02-20T23:11:20.893755",
13 "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
14 },
15 "custom": {
show all 41 linesSet channel members
setChannelMembers() sets members for one channel through a PubNub client for JavaScript and returns a page of the members of that channel.
channelrequired#- 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 andstatus.messageisChannel cannot be empty. uuidsrequired#- 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
idand the optionalcustom,type, andstatusproperties, for example{ id: "uuid-3", custom: { role: "Super Admin" } }. An empty array fails validation, andstatus.messageisUUIDs cannot be empty. include#- 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# - Whether the response includes
totalCount, the number of members of the channel. - property of include:
customFields# - Whether each member in the response includes its
customobject. - property of include:
statusField# - Whether each member in the response includes its
statusfield. - property of include:
typeField# - Whether each member in the response includes its
typefield. - property of include:
UUIDFields# - Whether each member includes the metadata of its user in the
uuidobject, such asnameandemail. - property of include:
customUUIDFields# - Whether the
uuidobject of each member includes thecustomobject of the user. - property of include:
UUIDStatusField# - Whether the
uuidobject of each member includes thestatusof the user. ThestatusFieldoption controls thestatusof the member instead. - property of include:
UUIDTypeField# - Whether the
uuidobject of each member includes thetypeof the user. ThetypeFieldoption controls thetypeof the member instead. sort#- 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 valuenullselects ascending order. The sortable properties areuuid.id, uuid.name, uuid.updated, uuid.status, uuid.type, updated, status, type. limit#- The maximum number of members to return in one response. The maximum value is
100. page#- The cursor that selects the page to return. Copy it from the
nextorprevproperty of an earlier response. - property of page:
next# - The cursor of the next page. Pass the
nextvalue of the previous response to continue forward. - property of page:
prev# - The cursor of the previous page. Pass the
prevvalue of the previous response to go back. PubNub ignoresprevwhen you also passnext.
API limits
To learn about the maximum length of parameters used to set channel members metadata, refer to REST API docs.
Sample code
Returns
The method returns aPromise that resolves to a SetMembersResponse.The data property lists the members of the channel after the change.status#- The HTTP status code of the response.
data#- The members of the channel on this page.
- property of data:
uuid# - The user of the member. With
UUIDFieldsset totrueit holds the user metadata, includingid,name,email,updated, andeTag. Otherwise it holds theidof the user and the user properties that the options request. - property of data:
status# - The status of the member. The property is present only when
statusFieldistrue. - property of data:
type# - The type of the member. The SDK always requests it.
- property of data:
custom# - The custom data of the member. The property is present only when
customFieldsistrue. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the member.
totalCount#- The number of members of the channel. The property is present only when
totalCountistrue. next#- The cursor of the next page.
prev#- The cursor of the previous page.
Examples for Set channel members
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>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": [
4 {
5 "uuid": {
6 "id": "uuid-1",
7 "name": "John Doe",
8 "externalId": null,
9 "profileUrl": null,
10 "email": "johndoe@pubnub.com",
11 "custom": null,
12 "updated": "2019-02-20T23:11:20.893755",
13 "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
14 },
15 "custom": {
show all 41 linesRemove 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.
channelrequired#- 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 andstatus.messageisChannel cannot be empty. uuidsrequired#- The users to remove from the members of the channel. An empty array fails validation, and
status.messageisUUIDs cannot be empty. include#- 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# - Whether the response includes
totalCount, the number of members of the channel. - property of include:
customFields# - Whether each member in the response includes its
customobject. - property of include:
statusField# - Whether each member in the response includes its
statusfield. - property of include:
typeField# - Whether each member in the response includes its
typefield. - property of include:
UUIDFields# - Whether each member includes the metadata of its user in the
uuidobject, such asnameandemail. - property of include:
customUUIDFields# - Whether the
uuidobject of each member includes thecustomobject of the user. - property of include:
UUIDStatusField# - Whether the
uuidobject of each member includes thestatusof the user. ThestatusFieldoption controls thestatusof the member instead. - property of include:
UUIDTypeField# - Whether the
uuidobject of each member includes thetypeof the user. ThetypeFieldoption controls thetypeof the member instead. sort#- 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 valuenullselects ascending order. The sortable properties areuuid.id, uuid.name, uuid.updated, uuid.status, uuid.type, updated, status, type. limit#- The maximum number of members to return in one response. The maximum value is
100. page#- The cursor that selects the page to return. Copy it from the
nextorprevproperty of an earlier response. - property of page:
next# - The cursor of the next page. Pass the
nextvalue of the previous response to continue forward. - property of page:
prev# - The cursor of the previous page. Pass the
prevvalue of the previous response to go back. PubNub ignoresprevwhen you also passnext.
Sample code
Returns
The method returns aPromise that resolves to a RemoveMembersResponse.The data property lists the members that remain in the channel.status#- The HTTP status code of the response.
data#- The members of the channel on this page.
- property of data:
uuid# - The user of the member. With
UUIDFieldsset totrueit holds the user metadata, includingid,name,email,updated, andeTag. Otherwise it holds theidof the user and the user properties that the options request. - property of data:
status# - The status of the member. The property is present only when
statusFieldistrue. - property of data:
type# - The type of the member. The SDK always requests it.
- property of data:
custom# - The custom data of the member. The property is present only when
customFieldsistrue. - property of data:
updated# - The date and time of the last update, in ISO 8601 format.
- property of data:
eTag# - The version hash of the member.
totalCount#- The number of members of the channel. The property is present only when
totalCountistrue. next#- The cursor of the next page.
prev#- The cursor of the previous page.
Examples for Remove channel members
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>;
Basic usage
1
Returns
1{
2 "status": 200,
3 "data": [
4 {
5 "uuid": {
6 "id": "uuid-1",
7 "name": "John Doe",
8 "externalId": null,
9 "profileUrl": null,
10 "email": "johndoe@pubnub.com",
11 "custom": null,
12 "updated": "2019-02-20T23:11:20.893755",
13 "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
14 },
15 "custom": {
show all 41 lines