Triggers and notifications
Write rules that turn silent app events into notifications and prepared turns, simulate them, and configure push delivery.
Three tabs: Rules, Simulate an app event, Push delivery. Rules apply to the environment in the top bar unless scoped to all.
Rules
The list shows each rule’s trigger (track("geofence_entered"), screen("checkout")), what it does (notify · banner · opens chat, agent speaks first, UI fixture, workflow), agent, environment scope, fire count, and an enable switch.
When the app…
| Field | Options |
|---|---|
| Kind | tracks an event · shows a screen · is idle (timer) · opens the chat (fires on the SDK’s kletso.chat_opened event; use the condition properties.messages <= 1 (greeting only) to fire only on an empty chat) |
| Event name / Screen | The track or screen name from the SDK |
| Delay (s) | Stored for future use; not applied yet |
| Audience | Everyone · Signed-in users · Anonymous visitors |
| Frequency cap | max fires per user per window (for example 3 per 1 h); leave max empty for unlimited |
| Environment | All environments or one |
| Condition | Expression over properties, context and user, for example properties.value > 1000 && context.plan == 'free' |
| Also require, judged by Jev (beta) | A yes/no question in plain words, evaluated by Jev over the event properties and the user’s public context, for example “Is this a high-value cart left by someone who has not bought before?”, with a probability threshold (default 0.7). The rule fires only when both the expression and the judgment pass. If Jev is unavailable the rule does not fire. |
Then…
Any combination of three reactions:
- Notify the app (
app.notify): title and body (templates such as{{ properties.store }}), channel with inline help (banner, toast, alert, system, silent), tap opens the chat, auto-dismiss seconds, an inline surface fixture, and a tap action: run a local action in the app (name and args), open a URL, or send a value to the agent. - Agent speaks first in the chat: a server-authored opening turn (
trigger.fired, then a streamed message) in the user’s open conversation, creating one if needed, optionally with a surface fixture such as quick replies. No model call is made. - Agent responds with AI: an instruction template the model answers through the normal agent loop, with the user’s context and every attached tool, without showing a user bubble. Use it for personalised openings (“call get_recommendations, render the best quests and offers as cards, greet by name”) or reactions to events (“the user completed {{ properties.quest }}; congratulate and suggest the next one”).
- Run a workflow: stored on the rule; live dispatch is planned.
The sample rules
| Rule | When | Then |
|---|---|---|
| Store geofence welcome | track("geofence_entered"), cap 5 per hour | Banner “You are near Acme {{ properties.store }}” that opens the chat, plus an opening turn with a store code and quick replies |
| Cart abandoned nudge | track("cart_abandoned"), cap 3 per hour | Opening turn mentioning {{ properties.value }} with quick replies |
| Checkout help | screen("checkout"), cap 3 per hour | Opening turn with the delivery media hub |
| Payment failed alert | track("payment_failed") | Alert “Payment did not go through” with a Retry payment local action (open_checkout) |
| Order shipped push | track("order_shipped") | System notification “Order {{ properties.orderId }} shipped” that opens the chat, with the trip-plan surface |
Simulate an app event
Pick track or screen, a name (with suggestions from existing rules), edit the properties JSON, and Fire in Development. The right card shows exactly what the app would receive, rendered through the same chat log and inspector as the preview, plus the raw app.notify payload. The simulation runs for real against the runtime for a synthetic user named simulator:<your email>, so it also appears in Conversations.
Push delivery
- Provider credentials: pick the secret holding your Firebase service-account JSON (Android and web via Firebase). Fields for Apple Push (.p8) and Web Push (VAPID) exist; delivery for those is planned.
- Devices with a push token: end users who registered a token through the SDK, with platform and last seen.
The payload sent to the provider carries the app.notify envelope under kletso; the SDK dedupes on notificationId. See Notifications and push.