Bottom Bar

The Bottom Bar is a single-line input docked bottom-center of the page, with conversation starters above it. It is disabled by default and does not render while the agent is open.

Starters come from conversation starters. Override them at runtime with setConversationStarters.

Settings

Field	Default	Meaning
enabled	false	Master gate for the feature. The Bottom Bar renders only when this is the literal boolean true. Any other value (including omitted) keeps it off.
maxVisibleStarters	5	How many conversation starters are shown in the bar at once. Capped at 5. On small screens the SDK shows at most 3 — this mobile cap is not configurable.
reopenFrequency	"EVERY_LOAD"	Controls when the bar may appear again after the user chooses Turn off bottom bar. Does not affect normal agent open/close — the bar returns when the agent closes unless the user explicitly dismissed it. "EVERY_LOAD" — next page load only, nothing persisted. "NEVER" — never again in this browser. "AFTER_DAYS" — again after reopenFrequencyDays days.
reopenFrequencyDays	30	Days to wait before showing the bar again when reopenFrequency is "AFTER_DAYS". Minimum 1. Ignored for other values of reopenFrequency.
starterClickBehavior	"OPEN_AGENT"	What happens when the user clicks a starter. "OPEN_AGENT" — open the full agent and send the starter text immediately. "FILL_INPUT" — type the starter into the bar input so the user can edit before submitting. Submitting from the input always opens the agent.
idleTimeoutMs	5000	In FULL mode, collapse to COMPACT after this many milliseconds without interaction. Set to 0 to disable auto-compact. Values greater than 0 are clamped to at least 2000.
initialBehaviorMode	"FULL"	How the bar first appears. "FULL" — input and starters visible. "COMPACT" — icon only (plus optional internal label if configured elsewhere).
openEmbeddedCallback	none	Callback invoked to reveal your embedded agent container when the user submits from the bar or opens the agent from the bar menu. Required in EMBEDDED mode — without it the Bottom Bar will not render. The prompt is delivered to the agent separately; this callback only makes the container visible.

Embedded mode

openEmbeddedCallback is required in EMBEDDED mode. See Embedded mode.

Examples

At init

foldspace('when', 'ready', () => {
  const agent = foldspace.agent({
    apiName: 'YOUR-AGENT-KEY',
    mode: 'OVERLAY',
    configuration: {
      bottomBarSettings: {
        // Master gate — must be literal `true` to render
        enabled: true,
        maxVisibleStarters: 5, // mobile render cap: 3 (not configurable)
        reopenFrequency: 'EVERY_LOAD', // 'EVERY_LOAD' | 'NEVER' | 'AFTER_DAYS'
        reopenFrequencyDays: 30,       // min 1; only used when reopenFrequency is 'AFTER_DAYS'
        starterClickBehavior: 'OPEN_AGENT', // 'OPEN_AGENT' | 'FILL_INPUT'
        idleTimeoutMs: 5000, // auto-compact in FULL; 0 disables
        initialBehaviorMode: 'FULL', // 'FULL' | 'COMPACT'
      },
    },
  });
});

At runtime

const agent = foldspace.agent('YOUR-AGENT-KEY');

agent.setConfiguration({
  bottomBarSettings: {
    enabled: true,
    maxVisibleStarters: 5,
    reopenFrequency: 'EVERY_LOAD',
    reopenFrequencyDays: 30,
    starterClickBehavior: 'OPEN_AGENT',
    idleTimeoutMs: 5000,
    initialBehaviorMode: 'FULL',
    // Required in EMBEDDED mode; no default
    openEmbeddedCallback: () => { /* reveal embedded container */ },
  },
});

openBottomBar

Open or expand the Bottom Bar programmatically. No-op when enabled is not true.

agent.openBottomBar(); // defaults to FULL

agent.openBottomBar({
  mode: 'FULL', // 'FULL' | 'COMPACT'
  idleTimeoutMs: 8000, // override idleTimeoutMs for this open only (FULL mode)
});

Route changes with page-specific starters

When navigation brings the user to a page with its own starters, update the starters and surface the bar:

function onRouteChange(route) {
  agent.setConversationStarters(route.starters, route.defaultStarterType);
  agent.openBottomBar({ mode: 'FULL' });
}

Typical trigger points: SPA route-change handlers, framework router afterNavigate hooks, or post–setConfiguration when page-level config is applied.