{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://parlane.ai/spec/push.schema.json",
  "title": "Push Payload",
  "description": "The push notification payload a backend sends to the relay (POST /notify). The relay routes it, content-opaque and encrypted, through the hosted APNs/FCM gateway to the app. Tapping the notification deep-links per `deepLink`; action buttons invoke backend tools (with the user's background-invocation permission). See docs/06-integration-kit.md §3 and 01-architecture.md §2.2.",
  "type": "object",
  "additionalProperties": false,
  "required": ["appId", "title", "body"],
  "properties": {
    "appId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the connected app this notification belongs to (routes to the right connection and mute settings)."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Notification title."
    },
    "body": {
      "type": "string",
      "maxLength": 2000,
      "description": "Notification body text."
    },
    "deepLink": {
      "type": "object",
      "additionalProperties": false,
      "required": ["target", "id"],
      "description": "Where tapping the notification navigates. Omit to open the app's default surface.",
      "properties": {
        "target": {
          "type": "string",
          "enum": ["thread", "dashboard"],
          "description": "Surface to open: a chat thread or a dashboard."
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Id of the thread (conversation_id) or dashboard to open."
        }
      }
    },
    "actions": {
      "type": "array",
      "maxItems": 3,
      "description": "Optional notification action buttons. Each invokes a backend tool directly (background tool invocation, permission-gated). APNs/FCM limit these to a small number.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["label", "tool"],
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40,
            "description": "Button label."
          },
          "tool": {
            "type": "string",
            "minLength": 1,
            "description": "Backend tool name invoked when the button is tapped."
          },
          "params": {
            "type": "object",
            "description": "Static parameters passed to the tool."
          }
        }
      }
    },
    "collapseId": {
      "type": "string",
      "maxLength": 64,
      "description": "Optional coalescing key; a newer notification with the same collapseId replaces the older one."
    }
  }
}