Payload reference
These fields belong to the notification payload: inside the WebSocket envelope’s JSON string, or directly in a UDP datagram.
| Field | Type | Default when omitted | Behavior |
|---|---|---|---|
title |
string | empty | Notification heading |
content |
string | empty | Notification body |
sourceApp |
string | empty | Sender label |
timeout |
number | 5 | Seconds; clamped to 0.5 to 60 |
opacity |
number | 1 | Clamped to 0 to 1 |
volume |
number | 1 | Parsed and clamped to 0 to 1; current playback uses the global sound-volume setting |
audioPath |
string | empty | Parsed for compatibility; custom asset loading is not implemented |
icon |
string | empty | Parsed for compatibility; custom asset loading is not implemented |
useBase64Icon |
boolean | false | Parsed for compatibility; custom asset loading is not implemented |
height |
integer | 0 | Carried for compatibility; card layout follows its content |
index |
integer | 0 | Carried for compatibility; does not create separate notification stacks |
type |
integer | 0 | Notification kind |
messageType |
integer | 0 | Legacy spelling of type; a nonzero value takes precedence |
At least one of title and content must contain non-whitespace text. Invalid JSON and empty notifications are discarded.
Missing values and explicit zero
Section titled “Missing values and explicit zero”Defaults apply when a field is absent. Explicit zero is preserved and then clamped: for example, timeout: 0 becomes 0.5 seconds, while opacity: 0 stays zero.
Presentation
Section titled “Presentation”The card uses a compact body with truncation for long messages. Avoid relying on a requested pixel height or on several cards appearing simultaneously.
Fields accepted by the parser do not necessarily imply full XSOverlay feature support. Read the compatibility page before depending on icons or custom audio.