Event / Action List
Event listeners wait for different PubNub events to occur, and when they do, the listener is activated. In the Events & Actions sense, an event may happen when:
- A message is published to a specific channel.
- A user with a particular Sender ID publishes a message.
- The message metadata matches a pattern you define.
Each event listener may have several actions associated with it. When an event happens, say a client with the User ID of thomas_anderson
publishes a message, PubNub triggers all actions associated with a particular event listener.
User ID / UUID
User ID is also referred to as UUID
/uuid
in some APIs and server responses but holds the value of the userId
parameter you set during initialization.
A listener with no associated actions will still be activated by a particular event, but no action will occur.
Actions per listener
The number of actions a single event listener may trigger depends on your Events & Actions tier.
Event source
The event source is the primary configuration option for each listener. It narrows down the area of your application the listener reacts to. The following event sources are available:
Messages
Event Producer | Event Type | Description |
---|---|---|
Pub/Sub | Message sent | Message was published on a channel. Events & Actions doesn't process the prefix/suffix-based internal publishes (such as Presence publishes to -pnpres channels). |
Message Action | Message action created | An action was added to a published message. |
Message action deleted | An action was removed from a published message. |
Users
Event Producer | Event Type | Description |
---|---|---|
Presence | User state changed in channel | User's Presence state changed on a channel. |
Channels
Event Producer | Event Type | Description |
---|---|---|
Presence | User started subscription to channel | User subscribed to a channel. |
User stopped subscription to channel | User unsubscribed from a channel. | |
User timed out while subscribing to channel | User didn't successfully subscribe to a channel because of a timeout. | |
First user subscribed to channel | User subscribed to a channel which didn't have any subscribers (the channel's occupancy changed from 0 to 1 ). | |
Last user left channel | User left a channel which now has no remaining subscribers (the channel's occupancy changed from 1 to 0 ). | |
Interval occupancy counted | Channel reported its current occupancy and user deltas at the configured interval. |
Mobile Push notifications
Event Producer | Event Type | Description |
---|---|---|
Devices | Device removed | Device token was removed from a channel. |
Push error | Mobile Push notification error was thrown. |
Filters
Filters allow you to specify the event conditions that trigger the actions. You can choose one of the following options to handle your messages:
Regardless of the filter type (apart from No filter), you can identify which message part should be parsed when deciding whether to trigger a listener. Advanced JSON path allows for the highest flexibility as it can look into different data points in the event payload.
No filter
Selecting No filter doesn't filter messages and triggers actions for all messages sent through the keyset.
Basic filters
Use Basic Filters to specify the Filters, Condition, and Value parameters.
Filters
Name | Description |
---|---|
Channel | Trigger an action after a message is published on a specific channel. |
Sender ID | Trigger an action after a message is published by a specific sender. |
Condition
Name | Description |
---|---|
Exact Match | Trigger an action only if there is an exact match. |
Contains | Trigger an action if the specified value is found within the filtered content. |
Value
This field requires your specific string value input.
Advanced JSON path
You can search for specific information contained in your message payload using a JSON inspection language called JSONPath. All events generated by PubNub follow a schema that's used to write JSON path expressions.
Let's say you want to filter a specific message containing the text: Wake up, Neo...
. For this purpose, you can use a JSONPath expression: $.message[?(@.text contains "Wake up, Neo...")]
. This searches for any message text that includes the phrase Wake up, Neo...
.
Let's inspect the following examples:
Match on | JSON path |
---|---|
Channel name with RegEx | $.[?(@.channel =~ /.*my_channel.*/i)] |
Fields in message payload | $.[?(@.message['some_property'] == 'some_value')] |
Fields in message metadata | $.[?(@.meta.sensor in ['warn', 'alert'])] |
Combination of fields | $.[?(@.channel =~ /.*some_suffix/i && @.meta.sensor_reading > 25 && @.message.status != 'error')] |
Refer to the JSONPath Online Evaluator to debug your JSONPath expressions.