Configure Events & Actions
The Events & Actions section in the Admin Portal allows for creating, editing, and deleting event listeners and specific actions that these listeners handle.
Event Listeners
The Event Listeners section allows you to see the number and type of event listeners you created, their status, and the number of actions they're connected to. Upon hovering, you can see the name of the action linked to the event listener. For more information, read how to create event listeners.
Actions
The Actions section allows you to see the number and type of actions you created, their status, and the number of event listeners they're connected to. Upon hovering, you can see the name of the event listener linked to the action. For more information, read how to create actions.
Create Event Listener
To create an event listener:
Open Admin Portal and choose Events & Actions.
Select your app and the corresponding keyset.
Click the + EVENT LISTENER button.
Choose a category for your event listener.
Name Description Messages Reacts to message events. Select the type of your event listener from the dropdown list.
Name Description Message Publish Triggers an action when a message is published. Select a filter type for the event listener from the dropdown list. Depending on your filter type selection, the flow for creating an event listener varies.
Name Description No filter No filtering done on conditions. Selecting this option triggers actions for all messages. Basic filters Predetermined conditions triggering an action selected from the UI. Advanced JSONPath Conditions triggering an action in a JSONPath format. You can pair your event listener with a previously created action without leaving the Event Listeners view. To do this, click the + ACTION button and select Choose an existing action.
Save your newly created event listener by clicking the SAVE CHANGES button.
Filter types
There are three types of filters available:
No filter
This filter doesn't require any configuration. Selecting this option triggers actions for all messages.
Basic filters
After choosing Basic filters, you will see two dropdown lists, Filters and Conditions, and an input field labeled Value.
From the Filters dropdown list, select one of the available 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. From the Conditions dropdown list, select one of the available conditions.
Name Description Exact Match Trigger an action only if there is an exact match. Contains Trigger an action if the specified value is found. In the Value field, type the value that must meet the selected condition. For example, choosing the exact match by the channel name
Matrix
will create an event listener that will trigger an action on every message published in theMatrix
channel.
Advanced JSONPath
Utilizing JSONPath allows for a much more robust setup of event handlers than basic filters.
You can use JSONPath to define the following conditions to trigger an action:
Condition name | 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.
To recreate the example from Basic Filters, you can use the following JSONPath query:$.[?(@.channel == "Matrix")]
.
This will trigger an action when your message is published to the Matrix
channel.
Create Action
Choose the category of your action and follow the configuration steps for each action category.
Name | Description |
---|---|
Webhook | Allows for a third-party service integration. |
Amazon SQS | Allows you to use a third-party message queuing service. |
Amazon Kinesis | Allows you to use a real-time, streaming data analysis service. |
Webhook payload example
The following JSON is an example of a webhook payload that is triggered when the message Wake up, Neo...
is sent by Client-w5h0y
on the channel Matrix
.
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.
{
"event": {
"eventCategory": "message",
"iso8601timestamp": "2022-05-11T17:48:53Z", // <timestamp for when publish is recorded by nginx on our edge>
"subscribeKey": "sub-c-eb78cd84-test-keys-8053-0a5864604ba8",
"eventPayload": {
"meta": null, // publish meta <json>
"message": { // publish message <json>
"text": "Wake up, Neo..."
}
},
"eventId": "0b8e84d6-test-test-b478-9774bca9aff3", // id of event, in this case the publish
"eventType": "message.publish",
"channel": "Matrix", // channel on which the publish was sent
"timetoken": "16522913332159825", // pubnub publish timetoken
show all 35 lines