PubNub Module

The PubNub module provides PubNub client API methods.

  1. The maximum recursion limit you can do is 3 - hops from one Function to another, using publish or fire, you can execute a maximum of three Functions.
  2. The combined maximum number within a single Function execution of KV store operations, XHRs, publish and fire is 3.

The PubNub module is made available via the following require statement:

const pubnub = require('pubnub');

Publish

Publish

To publish a message to PubNub Subscribers and Functions, use the publish() method.

Usage

publish({ message, channel })
ParameterTypeRequiredDescription
messageObjectYesJavaScript object to be sent to PubNub.
channelStringYesPubNub destination channel.
pubnub.publish({
"channel": "hello_universe",
"message": request.message
}).then((publishResponse) => {
console.log(`Publish Status: ${publishResponse[0]}:${publishResponse[1]} with TT ${publishResponse[2]}`);
});
JSON requirement

Payload that is published requires a valid JSON, strings will not trigger Function.

Fire

To publish a message to Functions only, use the fire() method.

Usage

fire({ message, channel })
ParameterTypeRequiredDescription
messageObjectYesJavaScript object to be sent to PubNub.
channelStringYesPubNub destination channel.
pubnub.fire({
"channel": "hello_universe",
"message": request.message
}).then((publishResponse) => {
console.log(`Publish Status: ${publishResponse[0]}:${publishResponse[1]} with TT ${publishResponse[2]}`);
});

Signal

To send a signal to PubNub Subscribers and Functions, use the signal() method.

By default, signals are limited to a message payload size of 64 bytes. This limit applies only to the payload, and not to the URI or headers. If you require a larger payload size, please contact support.

Usage

signal({ message, channel })
ParameterTypeRequiredDescription
messageObjectYesJavaScript object to be sent to PubNub.
channelStringYesPubNub destination channel.
pubnub.signal({
"channel": "hello_universe",
"message": request.message // must be smaller than 64 bytes
}).then((signalResponse) => {
console.log(`Signal Status: ${signalResponse[0]}:${signalResponse[1]} with TT ${signalResponse[2]}`);
});
JSON requirement

Payload that is published via signal requires a valid JSON, strings will not trigger Function.

File Sharing

At present, the main use case for Functions is to construct the URL and integrate with external services; for example, for image moderation, or for logging. To upload and download files, you need to use a PubNub client SDK

List files in channel

Retrieve the list of files uploaded to a channel.

Usage

listFiles accepts a single argument, a Javascript Object with the following properties:

listFiles({ channel, limit, next })
ParameterTypeRequiredDefaultDescription
channelStringYesRetrieve list of files for this channel.
limitNumberOptional100Number of files to return.
nextStringOptionalString token to get the next batch of files.
const pubnub = require('pubnub');

return pubnub.listFiles({
channel: 'my_channel',
limit: 2,
next: '10rX15WW7pyYsbwPY2h3ZlPfP1vSFl_3M6rCappuuCSULLIQb3MWOOba7xouJDxxs8yS9Ql6mxdz-1FmMdeiUE53GPMjNLmrUtefZdhoaswVwat7Z0Q6YzXi4FQYclt7pW_nQlOaC-vzaGSaeSB4QeQS2vlmjyiDVFYPQvSz6g39X7__1H73-XgogHZqqI-jnWMonp2fpgcQ',
}).then((res) => {
console.log(res);
}).catch((err) => {
// handle error
});

Returns

Returns a promise that resolves to an Object with the following format:

{
status: number,
data: Array<{
name: string,
id: string,
size: number,
created: string
}>,
next: string,
count: number,
}

For example:

{
status: 200,
data: [
{
name: 'cat_picture.jpg',
id: '0936618c-94f9-4e96-bd9c-aa4fd8719c28',
size: 31,
created: '2020-08-13T19:05:30Z'
},
{
name: 'my_other_file.jpg',
id: '2afb0f85-8eb3-43bf-84f9-5b4c7e031f8f',
size: 23,
created: '2020-08-13T19:07:22Z'
},
show all 19 lines

Get File URL

Get a file's direct download URL. This method doesn't make any API calls, and won't decrypt an encrypted file.

Usage

getFileUrl accepts a single argument, a Javascript Object with the following properties:

getFileUrl({ channel, id, name })
ParameterTypeRequiredDescription
channelStringYesChannel that the file was sent to.
idStringYesThe file's unique identifier.
nameStringYesName of the file.
const pubnub = require('pubnub');

const url = pubnub.getFileUrl({
channel: 'my_channel',
id: '12345678-1234-5678-123456789012',
name: 'cat_picture.jpg',
});

console.log(url);

Returns

Returns a string with the following format:

'https://ps.pndsn.com/v1/files/my-subkey/channels/my_channel/files/12345678-1234-5678-123456789012/cat_picture.jpg'

Delete file

Deletes a file from the specified channel.

Usage

deleteFile accepts a single argument, a Javascript Object with the following properties:

deleteFile({ channel, id, name })
ParameterTypeRequiredDescription
channelStringYesChannel that the file was sent to.
idStringYesThe file's unique identifier.
nameStringYesName of the file.
const pubnub = require('pubnub');

return pubnub.deleteFile({
channel: 'my_channel',
id: '12345678-1234-5678-123456789012',
name: 'cat_picture.jpg' ,
}).then((res) => {
console.log(res);
}).catch((err) => {
// handle error
});

Returns

Returns a promise that resolves to an Object with the following format:

{
status: 200,
}

Publish file message

Manually publish information about a previously uploaded file.

Usage

publishFile accepts a single argument, a Javascript Object with the following properties:

publishFile({ message, channel, fileId, fileName, storeInHistory, ttl, meta })
ParameterTypeRequiredDefaultDescription
channelStringYesChannel on which to send the file message
fileIdStringYesThe file's unique identifier
fileNameStringYesName of the file.
messageObjectOptionalMessage to attach to the file. The message can be any value that can be JSON stringified.
storeInHistoryBooleanOptionaltrueWhether published file messages should be stored in the channel's history. If storeInHistory isn't specified, then the history configuration on the key is used.
ttlNumberOptionalHow long the message should be stored in the channel's history, in hours. If not specified, defaults to the key set's retention value.
metaObjectOptionalAdditional metadata published with the message.
const pubnub = require('pubnub');

return pubnub.publishFile({
channel: 'my_channel',
fileId: '12345678-1234-5678-123456789012',
fileName: 'cat_picture.jpg',
message: {
someField: 'someValue',
},
}).then((res) => {
console.log(res);
}).catch((err) => {
// handle error
});

Returns

Returns a promise that resolves to an Object with the following format:

[ 1, "Sent", "15973568884237770" ]

Presence

Requires Presence add-on

This method requires that the Presence add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

Here Now

To fetch Here Now use the hereNow() method.

Usage

hereNow({ channels, channelGroups, includeUUIDs, includeState })
ParameterTypeRequiredDescription
channelsArrayOptionalchannels is an Array which specifies the channels to return occupancy results.
channelGroupsArrayOptionalchannelGroups is an Array which specifies the channelGroup to return occupancy results.
includeUUIDsBooleanOptionalSetting includeUUIDs to false disables the return of uuids.
includeStateBooleanOptionalSetting includeState to true enables the return of subscriber state information.
pubnub.hereNow({
channels: ["ch1"],
channelGroups : ["cg1"],
includeUUIDs: true,
includeState: true
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Where Now

To fetch Where Now use the whereNow() method.

Usage

whereNow({ uuid })
ParameterTypeRequiredDescription
uuidStringOptionaluuid specifies the uuid to return channel list for.
pubnub.whereNow({
uuid: "uuid"
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Global Here Now

To fetch Global Here Now use the hereNow() method.

Usage

hereNow({ includeUUIDs, includeState })
ParameterTypeRequiredDescription
includeUUIDsBooleanOptionalSetting includeUUIDs to false disables the return of uuids.
includeStateBooleanOptionalSetting includeState to true enables the return of subscriber state information.
pubnub.hereNow({
includeUUIDs: true,
includeState: true
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Set State

To fetch Set State use the setState() method.

Usage

setState({ channels, channelGroups, state, uuid })
ParameterTypeRequiredDescription
channelsArrayOptionalSpecifies the channels to get the state. Either channels or channelGroups should be provided.
channelGroupsArrayOptionalSpecifies the channelGroups to get the state. Either channels or channelGroups should be provided.
stateObjectOptionalstate is a JSON object of key/value pairs with supported data-types of int, float and string. Nesting of key/values is not permitted and key names beginning with prefix pn are reserved.
uuidStringOptionaluuid to set the current state.
pubnub.setState({
channels: ['ch1'],
channelGroups: ['cg1'],
state: newState,
uuid: "uuid"
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Get State

To fetch Set State use the getState() method.

Usage

getState({ uuid, channels, channelGroups })
ParameterTypeRequiredDescription
uuidStringOptionaluuid is the subscriber uuid to get the current state.
channelsArrayOptionalSpecifies the channels to get the state. Either channels or channelGroups should be provided.
channelGroupsArrayOptionalSpecifies the channelGroups to get the state. Either channels or channelGroups should be provided.
pubnub.getState({
uuid: "uuid",
channels: ['ch1'],
channelGroups: ['cg1']
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Access Manager

Requires Access Manager add-on

This method requires that the Access Manager add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

Grant

To grant permissions in Access Manager v2, use the grant() method.

Required secret key

Only server-side instances with a valid secret key can grant permissions to PubNub resources.

Usage

grant({ channels, channelGroups, uuids, authKeys, ttl, read, write, manage, delete, get, update, join})
ParameterTypeRequiredDescription
channelsArraySpecifying channels, channelGroups, or uuids is mandatory.Array which specifies the channel(s) to grant permissions to.
channelGroupsArraySpecifying channels, channelGroups, or uuids is mandatory.Array which specifies the channel group(s) to grant permissions to.
uuidsArraySpecifying channels, channelGroups, or uuids is mandatory.Array which specifies the UUID(s) to grant permissions to.
You can't grant permissions to channels or channel groups in the same request if you decide to use uuids.
This parameter does not support wildcards.
authKeysArrayOptionalArray which specifies the authorization credentials that should be granted access to selected resources.
authKeys are required for user-level grants. If you don't specify this parameter, the permissions will apply to all clients on the channel-level or application-level.
ttlNumberYesTime in minutes for which granted permissions are valid. The default value is 1440 (24hrs) and the allowed values range from 1 to 525600. If you set ttl to 0, it will apply the grant indefinitely.
readBooleanOptionalSet to true to grant read permissions. Set to false to remove permissions.
writeBooleanOptionalSet to true to grant write permissions. Set to false to remove permissions.
manageBooleanOptionalSet to true to grant manage permissions. Set to false to remove permissions.
deleteBooleanOptionalSet to true to grant delete permissions. Set to false to remove permissions.
getBooleanOptionalSet to true to grant get permissions. Set to false to remove permissions.
updateBooleanOptionalSet to true to grant update permissions. Set to false to remove permissions.
joinBooleanOptionalSet to true to grant join permissions. Set to false to remove permissions.
Max number of resources

There is a limit of up to 200 resources of the same type that you can request access to in a single grant API call.

pubnub.grant({
channels: [ch1, ch2],
channelGroups: [cg1, cg2],
authKeys: [key1, key2],
ttl: 12313,
read: true,
write: true,
manage: true
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Grant Token

To grant channel, channel group, and UUID permissions in Access Manager v3, use the grantToken() method.

Required secret key

Only server-side instances with a valid secret key can grant permissions to PubNub resources.

Usage

grantToken({ ttl, authorizedUuid, resources, patterns, meta })
ParameterTypeRequiredDescription
ttlNumberYesTotal number of minutes for which the token is valid.
  • The minimum allowed value is 1.
  • The maximum is 43,200 minutes (30 days).
authorizedUuidStringOptionalSingle uuid which is authorized to use the token to make API requests to PubNub.
resourcesObjectOptionalObject containing resource permissions.
resources.uuidsObjectOptionalObject containing uuid metadata permissions, for example: {"uuid-1": {get: true, update: true, delete: true},"uuid-2": {...}}.
resources.channelsObjectOptionalObject containing channel permissions, for example: {"channel-id-1": {read: true, write: true, manage: true, delete: true, get: true, update: true, join: true},"channel-id-2": {...}}.
resources.groupsObjectOptionalObject containing channel group permissions, for example: {"group-id-1": {read: true, manage: true},"group-id-2": {...}}.
patternsObjectOptionalObject containing permissions to multiple resources specified by a RegEx pattern.
patterns.uuidsObjectOptionalObject containing uuid metadata permissions to apply to all uuids matching the RegEx pattern, for example: {"uuid-pattern-1": {get: true, update: true, delete: true},"uuid-pattern-2": {...}}.
patterns.channelsObjectOptionalObject containing channel permissions to apply to all channels matching the RegEx pattern, for example: {"channel-pattern-1": {read: true, write: true, manage: true, delete: true, get: true, update: true, join: true}, "channel-pattern-2": {...}}.
patterns.groupsObjectOptionalObject containing channel group permissions to apply to all channel groups matching the pattern, for example: {"group-pattern-1": {read: true, manage: true}, "group-pattern-2": {...}}.
metaObjectOptionalExtra metadata to be published with the request. Values must be scalar only; arrays or objects aren't supported.
Required key/value mappings

For a successful grant request, you must specify permissions for at least one uuid, channel, or group, either as a resource sequence (resources) or as a regular expression (patterns).

pubnub.grantToken(
{
ttl: 15,
authorizedUuid: "my-authorized-uuid",
resources: {
channels: {
"channel-a": {
read: true
},
"channel-b": {
read: true,
write: true
},
"channel-c": {
read: true,
show all 48 lines

Revoke Token

The revokeToken() method is used by the server to revoke access to PubNub resources previously granted using the grantToken() method.

This method only applies to Access Manager v3.

Required secret key

Only server-side instances with a valid secret key can revoke permissions to PubNub resources.

Usage

revokeToken(token)
ParameterTypeRequiredDescription
tokenStringYesCurrent token with embedded permissions.
pubnub.revokeToken("p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenVzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJI")

Parse Token

The parseToken() method decodes an existing token and returns the object containing permissions embedded in that token. The client can use this method for debugging to check the permissions to the resources or find out the token's ttl details.

This method only applies to Access Manager v3.

Usage

parseToken(token)
ParameterTypeRequiredDescription
tokenStringYesCurrent token with embedded permissions.
pubnub.parseToken("p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenVzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJI")

Set Token

The setToken() method is used by the client devices to update the authentication token granted by the server.

This method only applies to Access Manager v3.

Usage

setToken(token)
ParameterTypeRequiredDescription
tokenStringYesCurrent token with embedded permissions.
pubnub.setToken("p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenVzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJI")

Channel Groups

Requires Stream Controller add-on

This method requires that the Stream Controller add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

Add Channels

To add channels to a channel group use channelGroups.addChannels().

Maximum number of channels

200 channels can be added to the channel group per API call.

Usage

channelGroups.addChannels({ channels, channelGroup })
ParameterTypeRequiredDescription
channelsArrayYeschannels is an Array, specifies channels to be added to a channelGroup.
channelGroupStringYeschannelGroup is a String, it specifies the channelGroup to add channels.
pubnub.channelGroups.addChannels({
channels: ['ch1', 'ch2'],
channelGroup: 'myChannelGroup'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

List Channels

To list all the channels of the channel group use channelGroups.listChannels().

Usage

channelGroups.listChannels({ channels })
ParameterTypeRequiredDescription
channelGroupStringYeschannelGroup is a String, specifies the channelGroup to list the channel(s).
pubnub.channelGroups.listChannels({
channelGroup: 'myChannelGroup'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Remove Channels

To remove the channels from the channel group use channelGroups.removeChannels().

Usage

channelGroups.removeChannels({ channels, channelGroup })
ParameterTypeRequiredDescription
channelsArrayYeschannels is an Array, specifies channels to remove from the channelGroup.
channelGroupStringYeschannelGroup is a String, specifies the channelGroup to remove the channels.
pubnub.channelGroups.removeChannels({
channels: ['ch1'],
channelGroup: 'myChannelGroup'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Delete Channel Group

To remove the channel group use channelGroups.deleteGroup().

Usage

channelGroups.deleteGroup({ channelGroup })
ParameterTypeRequiredDescription
channelGroupStringYeschannelGroup is a String, specifies the channelGroup to remove.
pubnub.channelGroups.deleteGroup({
channelGroup: 'myChannelGroup'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Message Persistence

Requires Message Persistence

This method requires that Message Persistence is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

History

To fetch History use the history() method.

Usage

history({ channel, reverse, count, stringifiedTimeToken, start, end })
ParameterTypeRequiredDescription
channelStringYesSpecifies channel to return history messages from.
reverseBooleanOptionalSetting to true will traverse the time line in reverse starting with the oldest message first. If both start and end arguments are provided, reverse is ignored and messages are returned starting with the newest message.
countNumberOptionalSpecifies the number of historical messages to return.
stringifiedTimeTokenBooleanOptionalIf stringifiedTimeToken is specified as true, the SDK will return timetoken values as a strings instead of integers. Usage of setting is encouraged in javascript environments which perform round-up/down on large integers.
startStringOptionalTimetoken delimiting the start of time slice (exclusive) to pull messages from.
endStringOptionalTimetoken delimiting the end of time slice (inclusive) to pull messages from.
export default (request) => {
var pubnub = require('pubnub');

return pubnub.history({
'channel' : 'my_channel',
'count' : 3,
'stringifiedTimeToken' : true,
'reverse' : true,
}).then((response) => {
console.log("startTT", response.startTimeToken);
console.log("endTT", response.endTimeToken);
response['messages'].forEach((value, index) => {
console.log("message:", value.entry, "timetoken:", value.timetoken);
});
return request.ok();
show all 17 lines

Batch History

To fetch History from multiple channels use the fetchMessages() method.

Usage

fetchMessages({ channels, count, start, end, stringifiedTimeToken })
ParameterTypeRequiredDescription
channelsArrayYesSpecifies channels to return history messages from.
countNumberOptionalSpecifies the number of historical messages to return per channel.
startStringOptionalTimetoken delimiting the start of time slice (exclusive) to pull messages from.
endStringOptionalTimetoken delimiting the end of time slice (inclusive) to pull messages from.
stringifiedTimeTokenBooleanOptionalIf stringifiedTimeToken is specified as true, the SDK will return timetoken values as a strings instead of integers.
pubnub.fetchMessages({
'channels' : ['my_channel', 'my_other_channel'],
'count' : 8,
'start' : '15343325214676133',
'end' : '15343325004275466',
'stringifiedTimeToken' : true,
}).then((status, response) => {
console.log(status);
console.log(response);
});

Delete Messages from History

To delete messages from the history use the deleteMessages() method.

Required setting

There is a setting to accept delete from history requests for a key, which you must enable by checking the Enable Delete-From-History checkbox in the key settings for your key in the Admin Portal.

Requires Initialization with secret key.

Usage

deleteMessages({ channel, start, end })
ParameterTypeRequiredDescription
channelStringYesSpecifies channel messages to be deleted from history.
startStringOptionalTimetoken delimiting the start of time slice (inclusive) to delete messages from.
endStringOptionalTimetoken delimiting the end of time slice (exclusive) to delete messages from.
pubnub.deleteMessages({
'channel' : 'my_channel',
'start': '15088506076921021',
'end': '15088532035597390',
}).then((result) => {
console.log(result);
});

Message Counts

Specifies the number of historical messages to return per channel. The count returned is the number of messages in history with a timetoken value greater than the passed value in the channelTimetokens parameter.

Usage

messageCounts({ channels, channelTimetokens })
ParameterTypeRequiredDescription
channelsArrayYesThe channels to fetch the message count.
channelTimetokensArrayYesList of timetokens, in order of the channels list. Specify a single timetoken to apply it to all channels. Otherwise, the list of timetokens must be the same length as the list of channels, or the function returns a PNStatus with an error flag.
pubnub.messageCounts({
'channels' : ['my_channel', 'my_other_channel'],
'channelTimetokens' : ['my_timetoken', 'my_other_timetoken'],
}).then((status, results) => {
console.log(status);
console.log(results);
});

Mobile Push

note
Requires Mobile Push Notifications add-on

This method requires that the Mobile Push Notifications add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

Add Device to Channel

To enable mobile push notifications on provided set of channels use push.addChannels().

Usage

push.addChannels({ channels, device, pushGateway })
ParameterTypeRequiredDescription
channelsArrayYesSpecifies channel to associate with mobile push notifications.
deviceStringYesThe device ID to associate with mobile push notifications.
pushGatewayStringYesapns, mpns or gcm.
pubnub.push.addChannels({
channels: ['my_channel', 'my_other_channel'],
device: 'nice_device',
pushGateway: 'apns'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

List Channels For Device

To request for all channels on which push notification has been enabled use push.listChannels().

Usage

push.listChannels({ device, pushGateway })
ParameterTypeRequiredDescription
deviceStringYesThe device ID to associate with mobile push notifications.
pushGatewayStringYesapns, mpns or gcm.
pubnub.push.listChannels({
device: 'nice_device',
pushGateway: 'apns'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Remove Device From Channel

To disable mobile push notifications on provided set of channels use push.removeChannels().

Usage

push.removeChannels({ channels, device, pushGateway })
ParameterTypeRequiredDescription
channelsArrayYesSpecifies channel to associate with mobile push notifications.
deviceStringYesThe device ID to associate with mobile push notifications.
pushGatewayStringYesapns, mpns or gcm.
pubnub.push.removeChannels({
channels: ['my_channel', 'my_other_channel'],
device: 'nice_device',
pushGateway: 'apns'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Remove all mobile push notifications

To disable mobile push notifications from all channels which is registered with specified pushToken use push.deleteDevice().

Usage

push.deleteDevice({ device, pushGateway })
ParameterTypeRequiredDescription
deviceStringYesThe device ID to associate with mobile push notifications.
pushGatewayStringYesapns, mpns or gcm.
pubnub.push.deleteDevice({
device: 'nice_device',
pushGateway: 'apns'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

App Context

Get Metadata for All Users

Returns a paginated list of UUID Metadata objects, optionally including the custom data object for each.

Usage

getAllUUIDMetadata({include, filter, sort, limit, page})
ParameterTypeRequiredDefaultDescription
includeObjectOptionalInclude additional fields in the response.
customFieldsBooleanOptionalfalseWhether to fetch custom fields.
totalCountBooleanOptionalfalseWhether to include totalCount in response.
filterStringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
sortObjectOptionalKey-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Sort directions are asc (ascending), desc (descending). For example: { name: 'asc' }
limitNumberOptional100Maximum number of results to return per page.
pageObjectOptionalUse for pagination.
nextStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
prevStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.getAllUUIDMetadata({
limit: 1,
include: {
customFields: true,
},
})
.then((resp) => {
console.log(resp);
return event.ok('Fetched uuid metadata successfully.');
})
.catch((error) => {
console.log(err);
show all 18 lines

Response

{
"status" : 200,
"data" : [
{
"name" : "my-name",
"updated" : "2020-07-16T21:10:38.770048Z",
"id" : "my-uuid",
"email" : "me@email.com",
"custom" : {
"foo" : "bar"
},
"externalId" : null,
"eTag" : "AePWsMnEl9m23wE",
"profileUrl" : null
}
show all 18 lines

Other Examples

To get next page of the results.

export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.getAllUUIDMetadata({
limit: 1,
include: {
customFields: true,
},
page: {
next: "Mg", // from previous response
},
})
.then((resp) => {
console.log(resp);
return event.ok('Fetched uuid metadata successfully.');
show all 21 lines

Response

{
"status": 200,
"data": [
{
"created": "2020-03-10T18:45:49.460388Z",
"eTag": "Ad+6yqHMr6TYxgE",
"email": null,
"externalId": null,
"id": "my-other-uuid",
"name": "my-other-name",
"profileUrl": null,
"updated": "2020-03-10T18:45:49.460388Z"
}
],
"next": "MQ",
show all 17 lines

Get User Metadata

Returns metadata for the specified UUID, optionally including the custom data object for each.

Usage

getUUIDMetadata({uuid, include})
ParameterTypeRequiredDefaultDescription
uuidStringYesUnique uuid identifier.
includeObjectOptionalSpecifies whether to include the uuid's custom data field.
customFieldsBooleanOptionaltrueWhether to fetch custom fields.
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.getUUIDMetadata({
uuid: 'my-uuid',
include: {
customFields: false,
},
})
.then((resp) => {
console.log(resp);
return event.ok('Fetched UUID metadata successfully.');
})
.catch((err) => {
console.log(err);
show all 18 lines

Response

{
"status" : 200,
"data" : {
"email" : "me@email.com",
"profileUrl" : null,
"externalId" : null,
"updated" : "2020-07-16T21:10:38.770048Z",
"name" : "my-name",
"eTag" : "AePWsMnEl9m23wE",
"id" : "my-uuid"
}
}

Set User Metadata

Set metadata for a UUID in the database, optionally including the custom data object for each.

Usage

setUUIDMetadata({ uuid, data, include })
ParameterTypeRequiredDefaultDescription
uuidStringYesUnique uuid identifier.
dataObjectYesObject with uuid metadata to set.
nameStringOptionalDisplay name for the uuid, maximum 200 characters.
externalIdStringOptionaluuid's identifier in an external system.
profileUrlStringOptionalThe URL of the uuid's profile picture.
emailStringOptionalThe uuid's email address, maximum 80 characters.
customObjectOptionalJSON object of key-value pairs with supported data types. Values must be scalar only; arrays or objects are not supported.
includeObjectOptionalInclude additional fields in the response.
customFieldsBooleanOptionaltrueWhether to fetch custom fields.
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.setUUIDMetadata({
uuid: 'my-uuid',
data: {
name: 'my-name',
email: 'me@email.com',
custom: {
foo: 'bar',
},
},
include: {
customFields: false,
},
show all 25 lines

Response

{
"status" : 200,
"data" : {
"email" : "me@email.com",
"profileUrl" : null,
"externalId" : null,
"updated" : "2020-07-16T21:10:38.770048Z",
"name" : "my-name",
"eTag" : "AePWsMnEl9m23wE",
"id" : "my-uuid"
}
}

Remove User Metadata

Removes the metadata from a specified UUID.

Usage

removeUUIDMetadata({ uuid })
ParameterTypeRequiredDescription
uuidStringYesUnique uuid identifier.
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.removeUUIDMetadata({
uuid: 'my-uuid',
})
.then((resp) => {
console.log(resp);
return event.ok('Removed UUID successfully.');
})
.catch((error) => {
console.log(err);
return event.abort('Failed to remove UUID metadata');
});
};

Response

{
"status": 200,
"data": null
}

Get Metadata for All Channels

Returns a paginated list of Channel Metadata objects, optionally including the custom data object for each.

Usage

getAllChannelMetadata({include, filter, sort, limit, page})
ParameterTypeRequiredDefaultDescription
includeObjectOptionalInclude additional fields in the response.
customFieldsBooleanOptionalfalseWhether to fetch custom fields.
totalCountBooleanOptionalfalseWhether to include totalCount in response.
filterStringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
sortObjectOptionalKey-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Sort directions are asc (ascending), desc (descending). For example: { name: 'asc' }
limitNumberOptional100Maximum number of results to return per page.
pageObjectOptionalUse for pagination.
nextStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
prevStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.getAllChannelMetadata({
limit: 1,
include: {
totalCount: true,
},
})
.then((resp) => {
console.log(resp);
return event.ok('Fetched channel metadata successfully.');
})
.catch((error) => {
console.log(err);
show all 18 lines

Response

{
"status" : 200,
"data" : [
{
"name" : "channel-name",
"description" : "What a great channel",
"updated" : "2020-07-16T21:18:12.156794Z",
"eTag" : "AeWFs+b3rMH4Dw",
"id" : "my-channel"
}
],
"totalCount" : 2,
"next" : "MQ"
}

Other Examples

To get next page of the results.

export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.getAllChannelMetadata({
limit: 1,
page: {
next: "MQ", // from previous response
},
})
.then((resp) => {
console.log(resp);
return event.ok('Fetched channel metadata successfully.');
})
.catch((error) => {
console.log(err);
show all 18 lines

Response

{
"status" : 200,
"data" : [
{
"updated" : "2020-07-16T21:19:28.735177Z",
"eTag" : "AeDH5/ixi/7lZw",
"id" : "my-other-channel",
"description" : "What another great channel",
"name" : "other-channel-name"
}
],
"prev" : "MQ",
"next" : "Mg"
}

Get Channel Metadata

Returns metadata for the specified Channel, optionally including the custom data object for each.

Usage

getChannelMetadata({channel, include})
ParameterTypeRequiredDefaultDescription
channelStringYesUnique channel identifier.
includeObjectOptionalSpecifies whether to include the channel's custom data field.
customFieldsBooleanOptionaltrueWhether to fetch custom fields.
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.getChannelMetadata({
channel: 'my-channel',
})
.then((resp) => {
console.log(resp);
return event.ok('Fetched channel metadata successfully.');
})
.catch((error) => {
console.log(err);
return event.abort('Failed to fetch channel metadata');
});
};

Response

{
"status" : 200,
"data" : {
"description" : "What a great channel",
"eTag" : "AeWFs+b3rMH4Dw",
"id" : "my-channel",
"updated" : "2020-07-16T21:18:12.156794Z",
"custom" : {
"foo" : "bar"
},
"name" : "channel-name"
}
}

Set Channel Metadata

Set metadata for a Channel in the database, optionally including the custom data object for each.

Usage

setChannelMetadata({ channel, data, include })
ParameterTypeRequiredDefaultDescription
channelStringYesUnique channel identifier.
dataObjectYesObject with channel metadata to set.
nameStringOptionalName of the channel.
descriptionStringOptionalDescription of the channel.
customObjectOptionalJSON object of key-value pairs with supported data types. Values must be scalar only; arrays or objects are not supported.
includeObjectOptionalInclude additional fields in the response.
customFieldsBooleanOptionaltrueWhether to fetch custom fields.
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.setChannelMetadata({
channel: 'my-channel',
data: {
name: 'channel-name',
description: 'What a great channel',
custom: {
foo: 'bar',
},
},
include: {
customFields: false,
},
show all 25 lines

Response

{
"status" : 200,
"data" : {
"eTag" : "AeWFs+b3rMH4Dw",
"id" : "my-channel",
"name" : "channel-name",
"description" : "What a great channel",
"updated" : "2020-07-16T21:18:12.156794Z"
}
}

Remove Channel Metadata

Removes the metadata from a specified channel.

Usage

removeChannelMetadata({ channel })
ParameterTypeRequiredDefaultDescription
channelStringYesUnique channel identifier.
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.removeChannelMetadata({
channel: 'my-channel',
})
.then((resp) => {
console.log(resp);
return event.ok('Removed channel successfully');
})
.catch((error) => {
console.log(err);
return event.abort('Failed to remove channel metadata');
});
};

Response

{
"data": null,
"status": 200
}

Get Channel Memberships

The method returns a list of channel memberships for a user. This method doesn't return a user's subscriptions.

Usage

getMemberships({uuid, include, limit, page, filter, sort})
ParameterTypeRequiredDefaultDescription
uuidStringYesUUID whose memberships you wish to retrieve.
includeObjectOptionalSpecifies whether to include additional fields in the response.
customFieldsBooleanOptionalfalseWhether to fetch custom fields.
channelFieldsBooleanOptionalfalseWhether to include fields for channel metadata.
customChannelFieldsBooleanOptionalfalseWhether to include custom fields for channel metadata.
totalCountBooleanOptionalfalseWhether to include totalCount in response.
limitNumberOptional100Maximum number of results to return per page.
pageObjectOptionalUse for pagination.
nextStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
prevStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
filterStringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
sortObjectOptionalKey-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Sort directions are asc (ascending), desc (descending). For example: { name: 'asc' }
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.getMemberships({
uuid: "my-uuid",
limit: 2,
})
.then((resp) => {
console.log(resp);
return event.ok('Fetched uuid memberships successfully.');
})
.catch((error) => {
console.log(err);
return event.abort('Failed to fetch memberships');
});
show all 16 lines

Response

{
"status" : 200,
"data" : [
{
"updated" : "2020-07-16T21:28:58.702287Z",
"channel" : {
"id" : "my-channel"
},
"eTag" : "AY39mJKK//C0VA"
},
{
"eTag" : "AY39mJKK//C0VA",
"updated" : "2020-07-16T21:28:21.992673Z",
"channel" : {
"id" : "my-other-channel"
show all 20 lines

Set Channel Memberships

Set channel memberships for a UUID.

Usage

setMemberships({uuid, channels, include, limit, page, filter, sort})
ParameterTypeRequiredDefaultDescription
uuidStringYesUUID whose memberships you wish to set.
channelsArrayYesArray of channels to set membership. Array can contain strings (channel-name only) or objects (which can include custom data).
includeObjectOptionalSpecifies whether to include additional fields in the response.
customFieldsBooleanOptionalfalseWhether to fetch custom fields.
channelFieldsBooleanOptionalfalseWhether to include fields for channel metadata.
customChannelFieldsBooleanOptionalfalseWhether to include custom fields for channel metadata.
totalCountBooleanOptionalfalseWhether to include totalCount in response.
limitNumberOptional100Maximum number of results to return per page.
pageObjectOptionalUse for pagination.
nextStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
prevStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
filterStringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
sortObjectOptionalKey-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Sort directions are asc (ascending), desc (descending). For example: { name: 'asc' }
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.setMemberships({
uuid: "my-uuid",
channels: [
"my-channel",
{ id: "my-other-channel", custom: { hello: "world" } },
],
include: {
channelFields: true,
customChannelFields: true,
customFields: true,
totalCount: true,
},
show all 25 lines

Response

{
"status" : 200,
"data" : [
{
"channel" : {
"id" : "my-channel"
},
"eTag" : "AY39mJKK//C0VA",
"custom" : null,
"updated" : "2020-07-16T21:28:58.702287Z"
},
{
"updated" : "2020-07-16T21:28:58.693461Z",
"custom" : {
"hello" : "world"
show all 32 lines

Remove Channel Memberships

Remove channel memberships for a UUID.

Usage

removeMemberships({uuid, channels, include, limit, page, filter, sort})
ParameterTypeRequiredDefaultDescription
uuidStringYesUUID from which to remove memberships.
channelsArrayYesArray of channels to remove from uuid memberships.
includeObjectOptionalSpecifies whether to include additional fields in the response.
customFieldsBooleanOptionalfalseWhether to fetch custom fields.
channelFieldsBooleanOptionalfalseWhether to include fields for channel metadata.
customChannelFieldsBooleanOptionalfalseWhether to include custom fields for channel metadata.
totalCountBooleanOptionalfalseWhether to include totalCount in response.
limitNumberOptional100Maximum number of results to return per page.
pageObjectOptionalUse for pagination.
nextStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
prevStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
filterStringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
sortObjectOptionalKey-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Sort directions are asc (ascending), desc (descending). For example: { name: 'asc' }
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.removeMemberships({
uuid: "my-uuid",
channels: [ "my-channel", "my-other-channel" ],
})
.then((resp) => {
console.log(resp);
return event.ok('Removed uuid memberships successfully.');
})
.catch((error) => {
console.log(err);
return event.abort('Failed to remove memberships');
});
show all 16 lines

Response

{
"status": 200,
"data": []
}

Get Channel Members

The method returns a list of members in a channel. The list will include user metadata for members that have additional metadata stored in the database.

Usage

getChannelMembers({channel, include, limit, page, filter, sort})
ParameterTypeRequiredDefaultDescription
channelStringYesChannel for which to retrieve members.
includeObjectOptionalSpecifies whether to include additional fields in the response.
customFieldsBooleanOptionalfalseWhether to fetch custom fields.
UUIDFieldsBooleanOptionalfalseWhether to include fields for uuid metadata.
customUUIDFieldsBooleanOptionalfalseWhether to include custom fields for uuid metadata.
totalCountBooleanOptionalfalseWhether to include totalCount in response.
limitNumberOptional100Maximum number of results to return per page.
pageObjectOptionalUse for pagination.
nextStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
prevStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
filterStringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
sortObjectOptionalKey-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Sort directions are asc (ascending), desc (descending). For example: { name: 'asc' }
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.getChannelMembers({
channel: "my-channel",
include: {
UUIDFields: true,
},
})
.then((resp) => {
console.log(resp);
return event.ok('Fetched channel members successfully.');
})
.catch((error) => {
console.log(err);
show all 18 lines

Response

{
"status" : 200,
"next" : "Mg",
"data" : [
{
"eTag" : "AbGV6rSh8LS/eg",
"uuid" : {
"id" : "my-other-uuid"
},
"updated" : "2020-07-16T21:40:48.367305Z"
},
{
"eTag" : "AY39mJKK//C0VA",
"uuid" : {
"profileUrl" : null,
show all 26 lines

Set Channel Members

This method sets members in a channel.

Usage

setChannelMembers({channel, uuids, include, limit, page, filter, sort})
ParameterTypeRequiredDefaultDescription
channelStringYesChannel for which to set members.
uuidsArrayYesArray of uuids to set as members. Array can contain strings (uuid-name only) or objects (which can include custom data).
includeObjectOptionalSpecifies whether to include additional fields in the response.
customFieldsBooleanOptionalfalseWhether to fetch custom fields.
UUIDFieldsBooleanOptionalfalseWhether to include fields for uuid metadata.
customUUIDFieldsBooleanOptionalfalseWhether to include custom fields for uuid metadata.
totalCountBooleanOptionalfalseWhether to include totalCount in response.
limitNumberOptional100Maximum number of results to return per page.
pageObjectOptionalUse for pagination.
nextStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
prevStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
filterStringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
sortObjectOptionalKey-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Sort directions are asc (ascending), desc (descending). For example: { name: 'asc' }
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.setChannelMembers({
channel: "my-channel",
uuids: [
"my-uuid",
{ id: "my-other-uuid", custom: { hello: "world" } },
],
})
.then((resp) => {
console.log(resp);
return event.ok('Set channel members successfully.');
})
.catch((error) => {
show all 19 lines

Response

{
"status" : 200,
"data" : [
{
"updated" : "2020-07-16T21:40:48.367305Z",
"eTag" : "AbGV6rSh8LS/eg",
"uuid" : {
"id" : "my-other-uuid"
}
},
{
"uuid" : {
"id" : "my-uuid"
},
"eTag" : "AY39mJKK//C0VA",
show all 20 lines

Remove Channel Members

Remove members from a Channel.

Usage

removeChannelMembers({channel, uuids, include, limit, page, filter, sort})
ParameterTypeRequiredDefaultDescription
channelStringYesChannel from which to remove members.
uuidsArrayYesArray of uuids to remove from channel members.
includeObjectOptionalSpecifies whether to include additional fields in the response.
customFieldsBooleanOptionalfalseWhether to fetch custom fields.
UUIDFieldsBooleanOptionalfalseWhether to include fields for uuid metadata.
customUUIDFieldsBooleanOptionalfalseWhether to include custom fields for uuid metadata.
totalCountBooleanOptionalfalseWhether to include totalCount in response.
limitNumberOptional100Maximum number of results to return per page.
pageObjectOptionalUse for pagination.
nextStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
prevStringOptionalRandom string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
filterStringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
sortObjectOptionalKey-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Sort directions are asc (ascending), desc (descending). For example: { name: 'asc' }
export default (event) => {
const pubnub = require('pubnub');

return pubnub.objects.removeChannelMembers({
channel: "my-channel",
uuids: [ "my-uuid", "my-other-uuid" ],
})
.then((resp) => {
console.log(resp);
return event.ok('Removed channel members successfully.');
})
.catch((error) => {
console.log(err);
return event.abort('Failed to remove members');
});
show all 16 lines

Response

{
"status": 200,
"data": []
}

Message Reactions

Add Message Reaction

Add an action on a published message.

Usage

addMessageAction({channel, messageTimetoken, action:{type, value}, uuid})
ParameterTypeRequiredDescription
channelStringYesName of channel which stores the message for which action should be added.
messageTimetokenStringYesTimetoken of message for which action should be added.
actionHashYesMessage action information.
action.typeStringYesWhat feature this message action represents.
action.valueStringYesValue which should be stored along with message action.
uuidStringYesThe uuid associated with the action.
pubnub.addMessageAction({
channel: 'channel1'
messageTimetoken: '15610547826970040',
action: {
type: 'reaction',
value: 'smiley_face',
},
uuid: 'uuid'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Remove Message Reaction

Remove a peviously added action on a published message.

Usage

removeMessageAction({channel, messageTimetoken, actionTimetoken, uuid})
ParameterTypeRequiredDescription
channelStringYesName of channel which store message for which action should be removed.
messageTimetokenStringYesTimetoken of message for which action should be removed.
actionTimetokenStringYesAction addition timetoken.
uuidStringYesThe uuid associated with the action.
pubnub.removeMessageAction({
channel: 'channel1'
messageTimetoken: '15610547826970040',
actionTimetoken: '15610547826970040',
uuid: 'uuid'
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Get Message Reactions

Get a list of message actions in a channel.

Usage

getMessageActions({channel, start, end, limit})
ParameterTypeRequiredDescription
channelStringYesName of channel from which list of messages actions should be retrieved.
startStringOptionalMessage action timetoken denoting the start of the range requested. Return values will be less than start.
endStringOptionalMessage action timetoken denoting the end of the range requested. Return values will be greater than or equal to end.
limitNumberOptionalNumber of message actions to return in response.
pubnub.getMessageActions({
channel: 'channel1',
start: '15610547826970041',
end: '15610547826970040',
limit: 100,
}).then((response) => {
console.log(response)
}).catch((error) => {
// handle error
});

Miscellaneous

Time

To request the current PubNub server time (timetoken), use the time() method.

pubnub.time().then((timetoken) => {
console.log(timetoken);
});
Functions support

Functions provides a rich set of tools, and this documentation does not cover all of the potential situations you may encounter. If you need help with a situation not covered by the documentation, please contact PubNub Support

Last updated on