Add WebSocket topic filter docs (#2465)

* Add WebSocket topic filter docs Refs openhab/openhab-core#4550. Signed-off-by: Florian Hotze <[email protected]> * Minor rewording Signed-off-by: Florian Hotze <[email protected]> --------- Signed-off-by: Florian Hotze <[email protected]>
openhab · Feb 20, 2025 · aec431d · aec431d
1 parent fa609cb
commit aec431d
Showing 1 changed file with 38 additions and 0 deletions.
diff --git a/configuration/websocket.md b/configuration/websocket.md
@@ -119,6 +119,43 @@ A new filter message always overrides the settings before.
 The default setting is no filter, i.e. all events from all sources.
 It is recommended to at least set a source filter for the client itself to prevent event reflection.
 
+#### Filter by topic (`openhab/websocket/filter/topic`)
+
+Topic filters can be used to include and/or exclude events of a specific topic from the event stream.
+They can be applied both inclusive and exclusive, and provide API compatibility with the existing topic filter functionality of the SSE event stream.
+
+Topics usually start with `openhab` and are split into several segments separated by an `/`, e.g. `openhab/items/MyItem/command` to listen to commands to `MyItem`.
+You may use `*` as a wildcard for a topic segment.
+To exclude a topic, start it with a `!`.
+
+When sending only exclude topics, all events except those excluded are sent.
+In other cases, only events of the selected topics are sent, whereas exclude topics can be used to filter out a subset of the selected events.
+
+The payload of the event contains a list of string with the topics:
+
+```json
+{
+    "type": "WebSocketEvent",
+    "topic": "openhab/websocket/filter/topic",
+    "payload": "[\"openhab/items/*/command\", \"!openhab/items/MyItem/command\"]",
+    "source": "WebSocketTestInstance",
+    "eventId": "10"
+}
+```
+
+This example will only send `ItemCommandEvents` for all Items except `MyItem`.
+
+The reception is acknowledged with the filter that is applied:
+
+```json
+{
+    "type": "WebSocketEvent",
+    "topic": "openhab/websocket/filter/topic",
+    "payload": "[\"openhab/items/*/command\", \"!openhab/items/MyItem/command\"]",
+    "eventId": "10"
+}
+```
+
 #### Filter by source (`openhab/websocket/filter/source`)
 
 Source filters can be used to remove events from a specific source from the event stream.
@@ -152,6 +189,7 @@ The reception is acknowledged with the filter that is applied:
 
 Type filters are used to select a specific sub-set of all available events.
 They are a inclusive, that means only those event types sent in the filter message are sent.
+
 The payload of the event contains a list of strings with the event names:
 
 ```json