Functions Overview

PubNub Functions enables you to write code, or leverage existing code, to achieve required business logic, whether transforming messages and data as they pass through PubNub, re-routing those messages, augmenting, filtering, and even aggregating data for subsequent use. PubNub Functions doesn't require you to spin-up your own servers or incur increased latency through call-outs to external server/serverless technology; the code you write or leverage runs within PubNub's operational environment, giving you the scale and speed that you need for your applications.

Add-on features

Some code and use cases in this documentation require add-on features, which you can enable via the PubNub Dashboard. Note that all new user accounts have a demo key with Functions enabled on it.

Example Use Cases

With PubNub Functions you can execute a variety of operations against your messages and data. You can also develop custom APIs that can be called directly from your own applications, services or processes. Some examples include:

• Chatbots run efficiently as Functions on PubNub's servers.

• Language translation mutates messages in-flight, altering the final message received by users to be in their requested language.

• Message moderation filters messages based on some of its attributes, so that only messages with acceptable content are passed to subscribing clients.

• Message routing forks the original message (or a modified version) to an alternate destination, such as to external storage.

• User blocking discards messages from specific users.

• Spam filtering detects spam messages and trashes them before they're sent to other users or recorded in history.

• Aggregation logic combines multiple messages into a single message to subscribing clients. For example, in large chat rooms, it can be more efficient to aggregate reactions or live poll results.

• Third-party integrations let you redirect message data to third-party services via web service calls.

The Blocks Catalog

Get inspired by perusing the PubNub Functions catalog! PubNub develops and maintains the Blocks Catalog, a large collection of predefined and customizable PubNub unctions. You can import Blocks from within the Portal itself. You can quickly integrate to third-party services in order do things like translate message content, integrate into a chatbot, or perform sentiment analysis on chat room content.

Function types

There are six Function types:

• Before Publish or Fire: code logic executed before messages are distributed to subscribers/users (synchronous)

• After Publish or Fire: code logic executed after messages are distributed to subscribers/users (asynchronous)

• Before Signal: code logic executed before signals are distributed to subscribers/users (synchronous)

• After Signal: code logic executed after signals are distributed to subscribers/users (asynchronous)

• After Presence code logic executed after presence events (join, leave) (asynchronous)

• On Request code logic executed upon URI request, e.g. curl or Web application (synchronous)

Synchronous (blocking) function types, such as Before Publish or Fire, operate on the original message, before it's delivered. The logic of the Function must complete before the message is released to continue its trip to the subscribers, which introduces a delivery delay (from microseconds for simple arithmetic, to potentially hundreds or thousands of milliseconds if interacting with a 3rd-party REST service).

Asynchronous (non-blocking) function types, such as After Publish or Fire, operate on a copy of the message, and don't increase delivery times. Asynchronous functions can't change the original message, the message received by the client is always identical to the message that triggered the Function.

The following sections describe these function types in greater detail.

Before Publish or Fire functions

These functions are synchronous (blocking).

Use a Before Publish or Fire function if you want to change a message in-flight (add a new attribute or modify an existing attribute). Some applications of Before Publish or Fire include:

• Translating a message from one language to another
• Conversion of values from Imperial to Metric
• Detecting (and censoring) profanity
• Detecting (and normalization) of missing or illegal values

After Publish or Fire functions

These functions are asynchronous (non-blocking).

Use an After Publish or Fire function if you want to pass the original message through the PubNub Data Stream Network intact, and also use it as a trigger to execute other logic (such as logging and message teeing). Some applications of After Publish or Fire include:

• Asynchronous third-party message logging (such as ElasticSearch)
• Mentions, keywords, and other string triggers
• Message teeing and forwarding

Before Signal functions

These functions are synchronous (blocking).

Use a Signal function if you want to change signal data (a small message sent using the Signal API) in-flight, either by adding a new attribute or modifying an existing attribute. Some applications of Before Signal include:

• Custom logic based on user typing; for example, when a customer starts typing after many minutes in a customer support chat, send an urgent message to the agent letting them know the customer has re-engaged
• Pass letters as they are being typed to a phrase dictionary for autosuggest/autocomplete functionality
• Integrate geographic data into the overall chat application experience

After Signal functions

These functions are asynchronous (non-blocking).

Use an After Signal function if you want to pass the original signal data through the PubNub Data Stream Network intact, and also use it as a trigger to execute other logic, such as integration with logging services. Some applications of After Signal include:

• Asynchronous third-party message logging (such as ElasticSearch)
• Saving typing state into user realtime profile
• Saving location data into user profile

After Presence functions

These functions are asynchronous (non-blocking), and trigger on subscriber (user) presence events, not messages. Presence events occur as users connect and disconnect from the realtime application, e.g. user enters a chat room, and a join event is triggered, while when they leave the chat room, a leave event occurs. The following Presence events are available:

Event	Description
join	A user subscribes to a channel.
leave	A user unsubscribes from a channel.
timeout	A timeout event is fired when a connection to a channel is severed and the subscriber has not been seen in 320 seconds (just over 5 minutes). This timeout interval can be customized using the heartbeat and heartbeat interval settings (SDK v3.6 or later).
state-change	state-change event will be fired anytime the state is changed using the state API (function signature varies by SDK).
interval	An occupancy count is sent every 10 seconds (the default setting for the Presence Interval property, which is also configurable in the Presence add-on panel in your account dashboard).

Presence Callbacks

The above events are also available as Callbacks, web hooks that can be called directly from the Presence service when these events occurred. Configured in your account dashboard, the HTTP callback URI must be publicly accessible. The callback logic could be managed by yourself, in your own environment on in a non-PubNub service, or it could be pointing to an On Request Function (see below).

Use an After Presence function type if you want to pass a presence event through the PubNub Data Stream Network intact, and also use it as a trigger to execute other logic (such as logging and message teeing). Some applications of After Presence include:

• Sending an SMS to an offline user when a member of their priority buddy-list comes online
• Updating an on-hold wait time KV store as JOIN and LEAVE events occur
• Monitor a user's online/offline time card as they JOIN and LEAVE an app

On Request functions

On Request functions let you create publicly accessible REST API methods. In addition to providing a lightweight approach to publicly accessing your PubNub code, you can also use on-request functions in your other functions as a replacement for pubnub.fire(). This offers several advantages, such as:

• Breaking your main function into smaller components for ease of maintainability
• Defining a utility function that you'll call from many other functions
• Returning data to the calling function for any number of reasons

Function Code Structure

Functions are implemented as JavaScript modules with a default export function. Inputs and outputs are generally the same in all circumstances, although there is some variation, to be documented here.

All Function Types, Except On Request

All Function Types, except the On Request one, share a common structure:

    export default (request) => {
        // Your code here
        return request.ok();
    };

In all circumstances, for non-On Request Function Types, the request object, passed in to the Function from within the PubNub network, has two methods and multiple attributes.

request Methods

Method	Arguments	Description
ok	message:String (Optional)	Returns a promise that resolves to the value of the request object.
abort	message:String (Optional)	Returns a promise that resolves to the value of the request object, with an error code.

request Attributes

Attribute	Type	Definition
message	Object	The actual user message sent to the channel.
verb	String	Method used by the publishing client when sending the message to PubNub.
pubkey	String	The Publish Key used when sending the message.
subkey	String	The Subscribe Key to retrieve the message.
channels	Array	The list of channels on which the message was sent on.
version	String	API Version.
meta.clientip	String	IP of the publishing client.
meta.origin	String	Origin defined on the publishing client.
meta.useragent	String	The Publishing client's useragent string.
params	Object	URL Parameters made on the request.
uri	String	The URI of the request.

On Request

The structure of the JavaScript code for the On Request Function Type is as follows:

    export default (request, response) => {
        // Your code here
        return response.send("Success!");
    };

The request object, passed in to the Function from within the PubNub network, has multiple attributes. The response object, passed back from the Function code, has multiple attributes as well as a sigle method.

request Attributes

Attribute	Type	Definition
verb	String	Method used by the publishing client when sending the message to PubNub. Always set to rest.
pubkey	String	The Publish Key used when sending the message.
subkey	String	The Subscribe Key to retrieve the message.
version	String	API Version.
meta.clientip	String	IP of the publishing client.
meta.origin	String	Origin defined on the publishing client.
meta.useragent	String	The Publishing client's useragent string.
params	Object	URL Parameters made on the request.
uri	String	The full path of the URI of the request minus PubNub hostname information.
path	String	The path minus PubNub and key specific information. This is the path configured, by you, for the Function itself.
method	String	The HTTP method of the request, e.g. GET, PUT, POST, DELETE.
body	Object	The body content if passed in the request.
headers	Object	The header information passed in the request.

response Methods

Method	Arguments	Description
send	body:String (Optional)	Returns a promise that resolves to the value of the response object.

response Attributes

Attribute	Type	Definition
status	Object	The HTTP status code to use when returning the response to the calling application or user.
body	Object	The body content returned to the calling application or user.
headers	String	Header information returned to the calling application or user.

Creating a new Function

tip

The code in this section calls vault.get() to retrieve a subscribe key (sub_key) stored in your module's secret store. Refer to the Vault Module documentation for more information.

Follow these instructions to create a Before Publish or Fire function that calls an On Demand function:

1. Go to the application instance on your PubNub Dashboard. Or, create a new application.

2. Create a new module, and then create a new Before Publish or Fire function.

3. Configure the function to trigger on specific channels, or use * to run it on all channels. The different function types are listed in Function types.

4. Copy your module's subscribe key.

5. Click My Secrets, and create a sub_key entry with a value of your subscribe key. Click Save, and close the panel.

6. Write the code for your function.

   The following sample calls a trivial On Request function:

   const auth = require ('codec/auth');
   const xhr = require('xhr');
   const vault = require('vault');
   
   export default (request) => {
       const http_options = {
           "timeout": 5000, // 5 second timeout.
           "method": "GET",
           headers: {
               "Authorization": auth.basic("super", "secure")
           }
       };
       return vault.get("sub_key").then((sub_key) => {
           const url = "https://pubsub.pubnub.com/v1/blocks/sub-key/" + sub_key + "/index.html";
           return xhr.fetch(url, http_options).then((x) => {
               console.log(x.body);
               return request.ok();
           });
       });
   };
   

7. Create a second function. This one should be an On Request function, listening on the path index.html.

   The On Request function's code is as follows:

   const auth = require('codec/auth');
   
   export default (request, response) => {
       const credentials = auth.basic("super", "secure");
   
       response.headers['Content-Type'] = 'text/plain';
   
       if (request.headers.authorization !== credentials) {
           response.status = 401;
           response.headers['WWW-Authenticate'] = 'Basic realm="FunctionsFTW"';
           return response.send("Unauthorized");
       }
   
       return response.send("Success!");
   };
   

8. Click the red Save button on the left, and then click Start Module on the right.

9. Test your function with a sample payload.

Further reading

For more information about PubNub Functions, refer to the Functions Quickstart. There are also tutorials and API and reference documentation available.