{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "FrontierBase Chatbot Script API Reference",
  "description": "Machine-readable API grammar for the FrontierBase chat widget. Call format: FrontierBase(command, payload). Use this spec for crawlers and AI tools.",
  "sourceUrl": "https://developers.frontierbase.io/chatbot",
  "lastUpdated": "2025-01-01",

  "callFormat": {
    "syntax": "FrontierBase(command, payload)",
    "description": "command is a string; payload is an optional object passed only when the command requires it."
  },

  "commands": [
    {
      "name": "boot",
      "purpose": "Initialize and show chatbot",
      "payloadRequired": true,
      "payloadSchema": "boot",
      "remarks": "pluginKey is required. Re-booting with the same pluginKey only refreshes the configuration."
    },
    {
      "name": "update",
      "purpose": "Update settings only (no re-init)",
      "payloadRequired": false,
      "payloadSchema": "update",
      "remarks": "Valid only after boot. Same fields as boot; all optional."
    },
    {
      "name": "open",
      "purpose": "Open chat panel",
      "payloadRequired": false,
      "payloadSchema": "open",
      "remarks": "Optional payload: dataset_ids."
    },
    {
      "name": "close",
      "purpose": "Close chat panel",
      "payloadRequired": false,
      "payloadSchema": null,
      "remarks": null
    },
    {
      "name": "toggle",
      "purpose": "Toggle panel open/close",
      "payloadRequired": false,
      "payloadSchema": null,
      "remarks": null
    },
    {
      "name": "destroy",
      "purpose": "Remove widget and cleanup",
      "payloadRequired": false,
      "payloadSchema": null,
      "remarks": null
    }
  ],

  "payloads": {
    "boot": {
      "description": "Initial configuration for the chat widget",
      "fields": [
        { "name": "pluginKey", "type": "string", "required": true, "description": "Channel ID; used to fetch channel-specific settings. Find at Console > Settings > Channel management > Button install & settings." },
        { "name": "mode", "type": "string", "required": false, "description": "Layout mode: 'floating' | 'overlay-fullscreen' | 'push-sidebar'. Default 'floating'." },
        { "name": "locale", "type": "string", "required": false, "description": "e.g. 'ko', 'en', 'es', 'fr', 'it', 'ja', 'zh'. Default 'en'." },
        { "name": "workspaceName", "type": "string", "required": false, "description": "Name shown in panel header. Default 'Chat'." },
        { "name": "contentSelector", "type": "string", "required": false, "description": "CSS selector for the wrapper element in push-sidebar mode (e.g. '#app', '#root', 'main'). If empty, SDK auto-detects." },
        { "name": "gaTrackingId", "type": "string", "required": false, "description": "Google Analytics measurement ID (e.g. G-XXXXXXXXXX). Available on PRO plans and above. Loads gtag and calls gtag('config', id) once." }
      ]
    },
    "update": {
      "description": "Same fields as boot; all optional. Use after boot to change settings at runtime."
    },
    "open": {
      "description": "Optional payload when opening the panel",
      "fields": [
        { "name": "dataset_ids", "type": "string[]", "required": false, "description": "RAG search target dataset IDs. When set, only those datasets are searched. When omitted or empty, backend auto-selects. For two or more datasets, specifying explicitly is recommended. Pass per open call when using different datasets per screen or page. dataset_id is found at Console > Settings > Dataset settings > dataset detail page." }
      ]
    }
  },

  "layoutModes": [
    { "value": "floating", "description": "Floating button bottom-right; rounded panel (~380×600px). On mobile opens full-screen. Default." },
    { "value": "overlay-fullscreen", "description": "Covers entire screen; mobile chat view centered." },
    { "value": "push-sidebar", "description": "Pushes main content left; sidebar in freed space. For SPAs use contentSelector. On mobile falls back to overlay-fullscreen." }
  ],

  "gaEvents": {
    "description": "When gaTrackingId is set at boot. Event names are fixed. Available on PRO plans and above.",
    "events": [
      { "trigger": "Chat panel opened", "event": "fb_chat_opened" },
      { "trigger": "Chat panel closed", "event": "fb_chat_closed" },
      { "trigger": "Panel toggle (open/close)", "event": "fb_chat_opened | fb_chat_closed" },
      { "trigger": "Message sent", "event": "fb_message_sent" },
      { "trigger": "Stream response completed (onDone)", "event": "fb_response_done" },
      { "trigger": "Conversation list (drawer) opened", "event": "fb_drawer_opened" },
      { "trigger": "New conversation button clicked", "event": "fb_new_conversation" }
    ]
  },

  "integration": {
    "scriptPlacement": "Place in head or near end of body. With defer, maintain correct DOM order.",
    "spaHandling": "SPAs that clear body may lose the widget. Call FrontierBase('destroy') then FrontierBase('boot', { ... }) after route changes.",
    "pushSidebarWrapper": "In push-sidebar mode specify contentSelector for main wrapper (#app, #root, etc.).",
    "csp": "Allow script domain https://cdn.frontierbase.io in script-src."
  }
}