Functions Basics

PubNub provides Functions to capture events that are happening on the PubNub Platform. Functions enables you to write code or leverage existing integrations to address your business needs, whether its transforming, re-routing, 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.

Functions API

For more information about the Funtions API, check out the Functions API documentation.

Event Types

There are numerous event types:

  • Before Publish or Fire: operates on a message before the message is distributed to subscribers/users (synchronous)

  • After Publish or Fire: operates on a copy of a message simultaneously with the original message being distributed to subscribers/users, and doesn't return a timetoken (asynchronous)

  • Before Publish File: operates on a message before files are distributed to subscribers/users (synchronous)

  • After Publish File: operates on a copy of a message simultaneously with files being distributed to subscribers/users, and doesn't return a timetoken (asynchronous)

  • Before Signal: operates on a message before signals are distributed to subscribers/users (synchronous)

  • After Signal: operates on a copy of a message simultaneously with the signal being distributed to subscribers/users, and doesn't return a timetoken (asynchronous)

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

  • On Request: code logic runs upon URI request, such as from curl or a Web application (synchronous)

  • On Interval: code logic runs every time interval, specified in milliseconds (asynchronous)

What Function Type to Use

Synchronous (blocking) event 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 third-party system).

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

Use a synchronous function if you need to do any of the following:

  • Block a message
  • Alter a message or its payload
  • Alter a message's meta information
  • Re-route a message to a different channel

For most other operations, you can use an asynchronous function.

You can also use both function types on a given channel. For example, if you want to change messages (synchronous), and also want to send data to an external system about them (asynchronous), split the logic between two functions, and keep the network I/O operations out of the synchronous function. This will keep the synchronous function's latency as low as possible, for the best user experience.

The following sections describe these function types in greater detail.

Before Publish or Fire Functions

These functions are synchronous.

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.

Use an After Publish or Fire function if you want to pass the original message through the PubNub Platform 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 Publish File

These functions are synchronous.

Use a Before Publish File function if you want to trigger code before the file message is published to a channel. Some applications of Before Publish File include:

  • Evaluating file contents via a third party AI/ML capabilities
  • Routing the message to a moderator channel if the service marks the file as inappropriate
  • Checking the file for copyright infringements via a third party service and possibly deleting the file from the storage service

After Publish File

These functions are asynchronous.

Use an After Publish File function if you want to trigger code after the file message is published to a channel. Some applications of After Publish File include:

  • Asynchronous file message logging
  • File message auditing
  • Business metrics gathering

Before Signal Functions

These functions are synchronous.

Use a Before 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're being typed to a phrase dictionary for automatic suggestion/completion functionality
  • Integrate geographic data into the overall chat application experience

After Signal Functions

These functions are asynchronous.

Use an After Signal function if you want to pass the original signal data through the PubNub Platform 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 real-time profile
  • Saving location data into user profile

After Presence Functions

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

EventDescription
joinA user subscribes to a channel.
leaveA user unsubscribes from a channel.
timeoutA timeout event is fired when a connection to a channel is severed and the subscriber hasn't 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-changeA state-change event will be fired anytime the state is changed using the state API (function signature varies by SDK).
intervalAn 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 admin portal).

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

Use an After Presence event type if you want to pass a presence event through the PubNub Platform 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

These functions are synchronous.

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

On Interval Functions

These functions are asynchronous.

On Interval functions let you create functionality that will execute automatically at the specified time interval. This functionality makes it easy to add in logic that would otherwise be located in other systems and servers, whether non-PubNub cloud or on-premises. The execution environment provides easy access to PubNub functionality and data. Some applications of On Interval include::

  • Periodically updating KV store cache data based on message data stored in history
  • Periodically sending packaged up message data for use in an external service
  • Periodically updating UUID metadata based on message activity