SDK configuration

The SDK accepts a single configuration object that controls how the agent looks, introduces itself, and behaves on the page. Pass it through setConfiguration on an agent instance:

foldspace.agent('API-KEY').setConfiguration({
  // settings go here
});

flowchart TD
  SC["setConfiguration({ })"]
  AP["Appearance & greeting<br/>name, logo, entry message"]
  PL["Placement & rendering<br/>position, render mode, drag"]
  TH["Theme<br/>colors, fonts, border"]
  DM["Dark mode<br/>dark theme, dark logo"]
  IC["Interaction<br/>timeout, voice, speech"]
  CS["Conversation starters<br/>prompts, defaults"]
  SO["Style overrides<br/>CSS-level customization"]
  SC --> AP
  SC --> PL
  SC --> TH
  SC --> DM
  SC --> IC
  SC --> CS
  SC --> SO

Settings are grouped into focused areas. Each grouped setting (such as theme) has its own reference page covering every key, its type, and its default value.

Setting groups

Group	What it controls
Appearance and greeting	The agent’s display name, logo, entry message, and prompt bar hint.
Placement and rendering	How the agent is embedded, anchored, and positioned on screen.
Theme	The colors and typography used in the agent interface.
Dark mode	Dark-theme colors and a dark-specific logo.
Interaction and communication	Session timeout, voice chat, speech-to-text, and new-conversation triggers.
Conversation starters	Predefined prompts and behavior for starting conversations.
Style overrides	CSS-level overrides for the entry button, speech bubble, and agent frame.
Border animation	The animated border around the agent entry point.
Share current tab	Let the agent read and understand the current page content.
Embedded configuration	Render the agent inline inside a specific DOM container.
Localization	Language override and developer-translated strings.

See also the full configuration example for a single snippet that uses every group together.

Studio and SDK precedence

flowchart TD
  ST["Studio settings<br/>dashboard UI"] --> D["Default values"]
  SDK["SDK setConfiguration<br/>code"] --> D
  SDK -->|"overrides"| ST
  D --> R["Rendered agent"]
  style SDK fill:#1842ef,stroke:#1842ef,color:#ffffff
  style R fill:#e8ecff,stroke:#1842ef,color:#0a0e1a

Configure every one of these settings visually in Studio. SDK configuration takes precedence over Studio values, so you can override defaults per page or per context directly in code.