PubNub FunctionsPubNub 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');

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

Usage

ParameterTypeRequiredDescription
message ObjectYesJavaScript object to be sent to PubNub.
channel String YesPubNub destination channel.
pubnub.publish({
    "channel": "hello_universe",
    "message": request.message
}).then((publishResponse) => {
    console.log(`Publish Status: ${publishResponse[0]}:${publishResponse[1]} with TT ${publishResponse[2]}`);
});
 
Payload that is published requires a valid JSON, strings will not trigger Function.

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

Usage

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

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

By default, signals are limited to a message payload size of 30 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

ParameterTypeRequiredDescription
message ObjectYesJavaScript object to be sent to PubNub.
channel String YesPubNub destination channel.
pubnub.signal({
    "channel": "hello_universe",
    "message": request.message // must be smaller than 30 bytes
}).then((signalResponse) => {
    console.log(`Signal Status: ${signalResponse[0]}:${signalResponse[1]} with TT ${signalResponse[2]}`);
});
 
Payload that is published via signal requires a valid JSON, strings will not trigger Function.

Requires Presence add-on XRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.

To fetch Here Now use the hereNow() method.

Usage

ParameterTypeRequiredDescription
channels ArrayOptionalchannels is an Array which specifies the channels to return occupancy results.
channelGroups ArrayOptionalchannelGroups is an Array which specifies the channelGroup to return occupancy results.
includeUUIDs Boolean OptionalSetting includeUUIDs to false disables the return of uuids.
includeState BooleanOptionalSetting 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 
});

To fetch Where Now use the whereNow() method.

Usage

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

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

Usage

ParameterTypeRequiredDescription
includeUUIDs BooleanOptionalSetting includeUUIDs to false disables the return of uuids.
includeState BooleanOptionalSetting 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 
});

To fetch Set State use the setState() method.

Usage

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.
state ObjectOptionalstate 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 
});

To fetch Set State use the getState() method.

Usage

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.
channelGroups ArrayOptionalSpecifies 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 
});

Requires Access Manager add-on XRequires that the Access Manager add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.

To Grant Permissions use the grant() method.

Usage

ParameterTypeRequiredDescription
channels Array Specifying either channels or channelGroups is mandatory.channels is an Array which specifies the channels to grant permissions to.
channelGroups ArraySpecifying either channels or channelGroups is mandatory.channelGroups is an Array which specifies the channelGroup to grant permissions to.
authKeysArray OptionalSetting which specifies the authKeys to grant permissions to.
ttl Number Yesttl is the Number which specifies the Time in minutes for which granted permissions are valid.
read Boolean Yesread permissions are granted by setting to true.
write Boolean Yeswrite permissions are granted by setting to true.
manageBooleanYesmanage permissions are granted by setting to true.
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 
});

To Grant channel and object permissions use the grantToken() method.

Usage

ParameterTypeRequiredDefaultsDescription
resourcesObjectSpecifying either resources or patterns is mandatorySet permissions by resource.
patternsObjectSpecifying either resources or patterns is mandatorySet permissions matching pattern.
ttlNumberOptional0Time to live for permission to be valid.
metaObjectOptionalCustom metadata included in token.
pubnub.grantToken({
    resources : {
        users : {
            user1 : {
                create : true,
            },
        },
        spaces : {
            space1 : {
                read : true,
            },
        },
        channels : {
            myChannel : {
                manage : true,
                delete : true,
            },
        },
        groups : {
            myGroup : {
                write : true,
            },
        },
    },
    patterns : {
        users : {
            '.*' : {
                manage : true,
                write : true,
            },
        },
        spaces : {
            '.*' : {
                delete : true,
            },
        },
        channels : {
            '^topic-[0-9a-f]*$' : {
                read : true,
                delete : true,
            },
        },
        groups : {
            '^:group-topic-*$' : {
                write : true,
            },
        },
    },
    ttl : 1440,
    meta : {
        foo : 'bar',
    },
}).then((token) => {
    console.log(token);
});

Requires Stream Controller add-on XRequires that the Stream Controller add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.

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

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

Usage

ParameterTypeRequiredDescription
channelsArrayYeschannels is an Array, specifies channels to be added to a channelGroup.
channelGroup StringYeschannelGroup 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
});

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

Usage

ParameterTypeRequiredDescription
channelGroup StringYeschannelGroup 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
});

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

Usage

ParameterTypeRequiredDescription
channelsArrayYeschannels is an Array, specifies channels to remove from the channelGroup.
channelGroup StringYeschannelGroup 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
});

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

Usage

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

Requires Storage & Playback add-on XRequires that the Storage & Playback add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.

To fetch History use the history() method.

Usage

ParameterTypeRequiredDescription
channel StringYesSpecifies channel to return history messages from.
reverse Boolean Optional

Setting 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.

count Number OptionalSpecifies 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.
startStringOptionalTime token delimiting the start of time slice (exclusive) to pull messages from.
endStringOptionalTime token 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();
    });
};

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

Usage

ParameterTypeRequiredDescription
channels ArrayYesSpecifies channels to return history messages from.
count Number OptionalSpecifies the number of historical messages to return per channel.
start String OptionalTime token delimiting the start of time slice (exclusive) to pull messages from.
end String OptionalTime token 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);
});

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

 
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 Administration Portal.

Requires Initialization with secret key.

Usage

ParameterTypeRequiredDescription
channelStringYesSpecifies channel messages to be deleted from history.
startStringOptionalTime token delimiting the start of time slice (inclusive) to delete messages from.
endStringOptionalTime token 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);
});

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

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);
});

Requires Mobile Push Notifications add-on XRequires that you enable the Mobile Push Notifications for your key. Refer to the following page for details on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.

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

Usage

ParameterTypeRequiredDescription
channelsArrayYesSpecifies channel to associate with push notifications.
deviceStringYesThe device id to associate with push notifications.
pushGateway StringYesapns, 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
});

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

Usage

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

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

Usage

ParameterTypeRequiredDescription
channelsArrayYesSpecifies channel to associate with push notifications.
deviceStringYesThe device id to associate with push notifications.
pushGateway StringYesapns, 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
});

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

Usage

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

Add an action on a published message.

Usage

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 a peviously added action on a published message.

Usage

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 a list of message actions in a channel.

Usage

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: '15610547826970040',
    end: '15610547826970040',
    limit: 100,
}).then((response) => { 
    console.log(response) 
}).catch((error) => { 
    // handle error 
});

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

pubnub.time().then((timetoken) => {
    console.log(timetoken);
});
 
PubNub 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.