Configure Events & Actions

Create an event listener in the Admin Portal to watch for a PubNub event. Then pair it with an action so PubNub forwards every matching event without you writing SDK code. For the concepts behind listeners, filters, and actions, see Events & Actions.

Create an event listener

1. Open the Admin Portal and select Events & Actions.
2. Select your app and keyset.
3. Click + Add Event Listener and choose an event source: Messages, Users, Channels, Mobile Push, or Membership. For the full list of event producers and event types under each source, see Event sources.
4. Choose the event producer and event type. If you don't see the event type you need, choose a different event source.
5. Select a filter type and configure it. See Choose a filter type below.
6. Pair the listener with an action. See Pair the listener with an action below.
7. Click Save Changes.

Choose a filter type

Pick the filter type that matches how precisely you need to target events:

Filter type	Use it when
No filter	You want the action to run for every event from the chosen source.
Basic filters	You want to match a single channel or sender ID.
Advanced JSONPath	You need conditions that basic filters can't express, such as matching on message content or excluding several channels.

No filter

If you want the action to run for every event from the chosen source, select No filter. It needs no further setup.

Basic filters

If you want to match a single channel or sender ID, select Basic filters, then:

1. From Filters, choose what to match on:

   Name	Description
   Channel	Match a message published on a specific channel.
   Sender ID	Match a message published by a specific sender.

2. From Conditions, choose how to match:

   Name	Description
   Exact Match	Match only when the value is identical.
   Contains	Match when the specified value appears anywhere in the filtered content.

3. In Value, enter the string to match. For example, an exact match on channel Matrix triggers the action for every message published to Matrix.

Advanced JSONPath

If basic filters can't express the condition you need, select Advanced JSONPath and enter a JSONPath expression. You can query these fields on the incoming event:

Field	Data type	Description
channel	string	Name of the channel the message was sent to.
message	any	Message content.
meta	any	Custom metadata.
uuid	string	Sender ID.

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.

Filters use the listener input, which calls the sender field uuid. Forwarded action payloads use event-specific field names. See Events & Actions payloads for the field in each event and envelope variant.

To recreate the basic filters example above, enter:

$.[?(@.channel == "Matrix")]

This triggers the action when a message is published to the Matrix channel.

Test your expression against a sample payload before you save it:

JSON Payload

{ "meta": { "sensor": "warn", "sensor_reading": 30 }, "message": { "text": "Wake up, Neo...", "status": "ok", "some_property": "some_value" }, "channel": "my_channel.some_suffix", "uuid": "thomas_anderson" }

✓Valid JSON

JSONPath Expression

✓Valid expression

For the complete event JSON schema and more JSONPath examples, see Payloads.

Pair the listener with an action

1. Without leaving Event Listeners, go to Add Action and pick an existing action. If you haven't created an action yet, create one first, then return here to pair it. For the full list of action types, see Available actions.

   Your Events & Actions tier sets how many actions a single listener can trigger.

2. Click Save Changes.

Confirm the listener fires

Publish a message, or trigger whichever event you configured, so it matches your filter. For how publishing works, see Publishing messages with PubNub.

In the Admin Portal, open Events & Actions and check the Event Listeners and Actions lists. Each list shows how many times a listener or action has run and, on hover, the name of what it's linked to. If the counts don't increase after you trigger the event, check that your filter matches the event you sent and that an action is paired with the listener.

Related tasks

• Events & Actions. Understand how listeners, filters, and actions fit together before you configure one.
• Event sources. Look up every event producer and event type you can select for a listener.
• Available actions. Compare every action type you can pair with a listener.
• Create a Webhook action. Forward matching events to your own HTTPS endpoint.
• Create an SQS action. Forward matching events to an Amazon SQS queue.
• Create a Kinesis action. Forward matching events to an Amazon Kinesis data stream.