Notifications (server to user)

Send an app.notify notification to an end user from your own backend with the secret key, for events that never touch the app.

Use this when your systems, not the app, know something the user should see: a shipment scanned at the depot, a refund approved, a price drop.

POST /v1/notifications
Authorization: Bearer kl_sec_live_…
Content-Type: application/json

{ "externalId": "user-42",                 // or "endUserId": "eu_…"
  "agentId": "agt_…",                      // optional; defaults to the project's first agent
  "notification": {
    "title": "Order ORD-2201 shipped",
    "body": "Arrives tomorrow. Tap to track it.",
    "channel": "system",                   // banner | toast | alert | system | silent (default banner)
    "openChat": true,
    "ttlSeconds": 30,
    "action": { "kind": "local", "name": "open_orders", "args": { "orderId": "ORD-2201" }, "label": "Track" },
    "surface": { "schema": "kletso.ui/v1", "…": "…" }
  } }

202:

{ "sent": true, "conversationId": "conv_…", "notificationId": "ntf_…" }

• title is required. Unknown user → 404.
• The notification is appended to the user’s latest open conversation as an app.notify event, delivered live if a socket is open, and pushed when the channel is system or no socket is attached (FCM today).
• externalId is the sub of the user’s host JWT, or visitor:<visitorId> for anonymous users.
• Supply your own notificationId to make retries idempotent on the client; otherwise one is minted.

The app handles the result exactly like a rule-produced notification: KletsoNotificationHost shows it, a tap opens the chat and runs the action. See Notifications and push.