Skip to content

Configuration Reference ​

All fields in VAssistEmbedConfig. Every field is optional. Unspecified fields fall back to defaults during normalizeVAssistEmbedConfig().

The same config object is shared by @vassist/embed and @vassist/react.

Use this page once you already know the integration surface you need:

ts
import type { VAssistEmbedConfig } from "@vassist/embed";

mount ​

Controls where and how the embed instance is mounted into the DOM.

FieldTypeDefaultDescription
targetHTMLElement | string | nullInject helpers use document.body when omittedMount target for inject and auto-inject flows
hostIdstring"vassist-embed-root"Stable identifier for this instance
shadowRoot"open" | "closed" | false"open"Shadow root mode. Set false to mount directly into the host element
autoInjectbooleantrueWhether window.VAssistEmbedConfig should auto-mount when the module loads
runtimeIsolation"shadow-root" | "iframe""shadow-root"Whether the runtime renders directly or inside an isolated iframe
portalContainersVAssistPortalContainersConfig{}Host-supplied portal targets for popovers, canvas portals, and future overlay routing

mount.runtimeIsolation ​

  • "shadow-root": default. Renders inside the host element's shadow root unless shadowRoot is false.
  • "iframe": mounts the runtime in an isolated child iframe while preserving the same public host API.

mount.portalContainers ​

Portal targets accept a CSS selector string, an HTMLElement, a ShadowRoot, or null.

KeyCurrent use
overlaysReserved. No built-in surface is routed here today, so most hosts can ignore it
popoversUsed by select menus and the remote model picker
canvasUsed by the Live Assistant canvas portal

Selector strings are resolved at runtime. If a selector does not resolve, the affected UI surface falls back to its default container.

ts
mount: {
  target: document.querySelector("#assistant-slot"),
  hostId: "my-assistant",
  runtimeIsolation: "shadow-root",
  portalContainers: {
    popovers: "#assistant-popovers",
    canvas: document.body,
  },
}

shell ​

Controls which shell variant renders and how the initial setup flow works.

FieldTypeDefaultDescription
mode"full" | "chat-only" | "chat-toolbar" | "toolbar-only""full"Shell preset. Determines the default feature set
deferSetupUntilStartedbooleanfalseWhen true, setup UI stays deferred until the user actively opens the assistant
controlDockInsets{ top?, right?, bottom?, left? }All 0Reserve nonnegative CSS pixels around the assistant dock and its palettes for host navigation or footers. The dock scales to keep the chat button reachable.
forcePortraitModebooleanfalseForce portrait layout regardless of viewport size

If setup.mode is omitted, shell.deferSetupUntilStarted: true also implies setup.mode: "deferred".

Shell mode feature defaults ​

Featurefullchat-onlychat-toolbartoolbar-only
chat✓✓✓-
history✓✓✓-
settings✓✓✓-
voiceInput✓✓✓-
voiceCall✓✓✓-
voiceOutput✓✓✓-
aiToolbar✓-✓✓
liveAssistant3d✓---
camera✓✓✓-
screenShare✓✓✓-
xr----

features ​

Override individual feature flags on top of the shell preset defaults.

FeatureDescription
chatChat input and message thread
historySaved conversations panel
settingsIn-app settings panel
voiceInputMicrophone input for voice-to-text
voiceCallReal-time voice conversation mode
voiceOutputTTS playback of assistant responses
aiToolbarPage-level AI toolbar for text actions
liveAssistant3d3D Live Assistant avatar
cameraCamera capture for visual input
screenShareScreen share for visual context
xrOpt into experimental WebXR with native HTML spatial panels. Requires liveAssistant3d.

Normalization also applies a few safety rules:

  • If voiceCall is disabled, camera and screenShare are forced off.
  • If chat is disabled, history and settings are forced off.
  • If liveAssistant3d is disabled, the 3d settings tab is hidden automatically.
ts
features: {
  liveAssistant3d: false,
  screenShare: false,
  camera: false,
}

ui ​

Optional host defaults for shared UI settings. This is a deep partial of UIConfig, exported as VAssistUIConfig. Values merge over saved settings on startup and when the host updates the config. Feature and theme constraints still take precedence. Most integrations can omit ui and let users manage their own settings.

Browser embeds ignore UI settings that require Electron or Android services.

FieldDefaultBehavior
stage{ selection: null, options: {}, calibration: {} }Native App and Wallpaper stage selection, per-environment options, and per-avatar alignment. Stages are omitted during Android AR. See Stages.
enableAvatarShadowtrueWith no stage, show the avatar silhouette behind the character. With a stage, enable its real 3D cast shadow.

stage.selection is null until the user chooses an environment, or one of { kind: "none" }, { kind: "builtin", id }, or { kind: "custom", id }. stage.options is keyed by stage ID and stores partial lighting, season, animation, and brightness settings. stage.calibration is keyed by avatar ID and stores heightMeters (default 1.65) and floorOffset (default 0). The UI and runtime apply only options supported by the selected stage.

stage.options[stageId] fieldDefaultBehavior
mood""Named lighting preset when the selected stage supports moods.
hour15.5Manual local-stage time, from 0 to 24 in quarter-hour steps.
localTimetrueFollow the device's local clock when time lighting is selected.
lightingModeInferred"time" or "mood". Mood mode is only offered by stages with named moods.
season"auto"Local-calendar season, or spring, summer, autumn, or winter.
seasonalEffectstrueEnable seasonal particles where the environment supports them.
brightness1Stage brightness multiplier, clamped to 0.35–1.5.
animatetrueEnable stage-provided animation such as water, stars, rain, or fire.

stage.calibration[avatarId] has heightMeters and floorOffset fields. These adjust stage/avatar alignment without changing the avatar's physics rig. The selected built-in or custom stage and its options are shared across supported native app and wallpaper modes. Android AR suppresses stage rendering while active.

Native background settings ​

These fields belong to shared UIConfig and can be persisted by the native apps. They also type-check inside a host's ui override, but require the owning platform's storage or IPC services to render images.

FieldDefaultBehavior
desktopBackground.modeimagesRender images, a solid color, or a gradient.
desktopBackground.solidColor#111827Solid background color in six-digit hexadecimal form.
desktopBackground.gradientStartColor#101827Gradient start color in six-digit hexadecimal form.
desktopBackground.gradientEndColor#243b63Gradient end color in six-digit hexadecimal form.
desktopBackground.gradientAngleDegrees135Gradient angle from 0 to 360 degrees.
desktopBackground.enabledtrueRender selected backgrounds in App and Wallpaper modes. Floating stays transparent.
desktopBackground.builtInIds['milky-way']Select bundled backgrounds. The first ID is shown first.
desktopBackground.parallaxEnabledtrueIn App and interactive Wallpaper mode, follow mouse movement.
desktopBackground.slideshowEnabledtrueFade through selected built-in and custom images when more than one is available.
desktopBackground.folderPathnullOriginal desktop folder path, combined with selected built-in images when present.
desktopBackground.imagePaths[]Original custom desktop image paths. An empty list means no custom files are selected.
desktopBackground.slideshowIntervalSeconds30Hold each image for 5 to 3600 seconds before beginning the next fade.
desktopBackground.fadeDurationSeconds2Fade between images over 0 to 15 seconds.
desktopBackground.brightnessPercent60Background brightness from 20% to 100%.
desktopBackground.contrastPercent100Background contrast from 50% to 150%.
desktopBackground.saturationPercent100Color saturation from 0% to 200%.
desktopBackground.blurPixels0Blur radius from 0 to 12 pixels.
desktopBackground.grayscalePercent0Grayscale amount from 0% to 100%.
desktopBackground.sepiaPercent0Sepia amount from 0% to 100%.
desktopBackground.hueRotateDegrees0Hue rotation from 0 to 360 degrees.
androidBackground.modeimagesRender images, a solid color, or a gradient.
androidBackground.solidColor#111827Solid background color in six-digit hexadecimal form.
androidBackground.gradientStartColor#101827Gradient start color in six-digit hexadecimal form.
androidBackground.gradientEndColor#243b63Gradient end color in six-digit hexadecimal form.
androidBackground.gradientAngleDegrees135Gradient angle from 0 to 360 degrees.
androidBackground.enabledtrueShow or hide the background in the Android app and live wallpaper.
androidBackground.builtInIds['milky-way']Select bundled backgrounds. The first ID is shown first.
androidBackground.slideshowEnabledfalseCycle through selected built-in and imported backgrounds in the Android app and live wallpaper.
androidBackground.parallaxEnabledtrueFollow phone tilt and rotation with a smooth return toward center when the phone settles.
androidBackground.slideshowIntervalSeconds30Hold each image for 5 to 3600 seconds before beginning the next fade.
androidBackground.fadeDurationSeconds2Fade between images over 0 to 15 seconds.
androidBackground.brightnessPercent60Background brightness from 20% to 100%.
androidBackground.contrastPercent100Background contrast from 50% to 150%.
androidBackground.saturationPercent100Color saturation from 0% to 200%.
androidBackground.blurPixels0Blur radius from 0 to 12 pixels.
androidBackground.grayscalePercent0Grayscale amount from 0% to 100%.
androidBackground.sepiaPercent0Sepia amount from 0% to 100%.
androidBackground.hueRotateDegrees0Hue rotation from 0 to 360 degrees.

Bundled wallpaper files ship with each native app. Android custom image blobs and their active state use background asset storage. Desktop built-ins are packaged under Electron resources, while user-selected files remain at their original paths. See UI Settings and Storage and Data for the platform workflows and backup behavior.

settings ​

Controls which settings tabs, subtabs, sections, and fields are visible or editable in the in-app settings UI.

FieldTypeDefaultDescription
hiddenTabsVAssistSettingsTabId[][]Hide full settings tabs
readOnlyTabsVAssistSettingsTabId[][]Show tabs but prevent editing
hiddenFieldsstring[][]Legacy string list. Matching known target IDs are folded into policy.hidden during normalization
policyVAssistSettingsPolicy{ hidden: [], readOnly: [] }Preferred typed settings policy API

Supported tab IDs ​

ts
"ui";
"3d";
"llm";
"tts";
"stt";
"ai-plus";

Supported subtab IDs ​

ts
"llm.provider";
"llm.routing";
"llm.decision";
"llm.profiles";

Supported section IDs ​

ts
"ui.appearance";
"ui.aiToolbar";
"ui.storage";
"ui.developer";
"llm.provider";
"llm.routing";
"llm.decision";
"llm.profiles";
"tts.provider";
"tts.remoteProfiles";
"stt.provider";
"stt.remoteProfiles";
"ai-plus.translator";
"ai-plus.languageDetector";
"ai-plus.summarizer";
"ai-plus.rewriter";
"ai-plus.writer";

Supported field IDs ​

ts
"ui.aiToolbar.enabled";
"ui.aiToolbar.showOnInputFocus";
"ui.aiToolbar.showOnImageHover";
"llm.provider.select";
"llm.openai.apiKey";
"llm.openai.model";
"llm.openai.endpoint";
"llm.ollama.endpoint";
"llm.ollama.apiFormat";
"llm.ollama.apiKey";
"llm.ollama.model";
"llm.routing.visionModel";
"llm.routing.routerModel";
"llm.decision.enabled";
"llm.decision.provider";
"llm.decision.endpoint";
"llm.decision.model";
"llm.decision.apiKey";
"llm.decision.timeoutMs";
"llm.decision.contextSize";
"tts.enabled";
"tts.accurateLipSync";
"tts.legacyLipSync";
"tts.provider.select";
"tts.openai.apiKey";
"tts.openai.model";
"tts.openaiCompatible.endpoint";
"tts.openaiCompatible.apiKey";
"tts.openaiCompatible.model";
"tts.gptsovitsRemote.endpoint";
"tts.gptsovitsRemote.model";
"stt.enabled";
"stt.provider.select";
"stt.openai.apiKey";
"stt.openai.model";
"stt.openaiCompatible.endpoint";
"stt.openaiCompatible.apiKey";
"stt.openaiCompatible.model";

LLM parameter settings use provider-specific targets in the form llm.<provider>.<parameter>. Providers are openai, ollama, desktop-local, android-local, and chromeAi. Parameter names follow the current LLMParameters type, including temperature, maxTokens, topP, topK, minP, repeatPenalty, seed, contextSize, gpuLayers, batchSize, flashAttention, cacheTypeK, and ropeScaling.

Current runtime behavior ​

  • hiddenTabs and readOnlyTabs apply to their nested settings rows and subtabs as well as the top-level tab.
  • policy.hidden and policy.readOnly are the preferred typed APIs. Unknown IDs are ignored during normalization.
  • hiddenFields still works as a legacy alias when the strings match the supported target IDs above.
  • openSettings({ target }) uses the same target vocabulary to resolve the owning tab.
  • The current UI supports direct LLM subtab navigation and enforces hide/read-only behavior on the tagged settings rows backed by the field IDs above.
  • Hiding or making llm.decision read-only applies to the complete Decision subtab. Decision fields can also be targeted individually.
  • Section IDs are part of the public target vocabulary. Behavior applies where the current UI explicitly wires that section target.
ts
settings: {
  hiddenTabs: ["3d"],
  policy: {
    readOnly: [
      "llm",
      "tts",
      "stt",
      "llm.provider.select",
      "tts.provider.select",
      "stt.provider.select",
    ],
    hidden: ["ui.aiToolbar.showOnImageHover"],
  },
}

aiToolbar ​

Host policy for the built-in AI toolbar UI.

This is different from features.aiToolbar:

  • features.aiToolbar: false disables the toolbar feature entirely.
  • aiToolbar keeps the feature enabled, but changes where it appears and which built-in items are visible.
FieldTypeDefaultDescription
showOnInputFocusbooleantrueWhether the toolbar can appear when an editable field receives focus
showOnImageHoverbooleantrueWhether the toolbar can appear when the user hovers an image
visibleItemsVAssistToolbarItemId[]undefinedOptional whitelist of built-in toolbar items to show
hiddenItemsVAssistToolbarItemId[][]Built-in toolbar items to hide
itemOrderVAssistToolbarItemId[]default built-in orderReorders built-in toolbar items and subgroup options

The runtime applies the policy in this order:

  1. Start from the default built-in item list.
  2. Apply visibleItems if present.
  3. Remove anything in hiddenItems.
  4. Sort remaining items by itemOrder, then append unspecified items in their default order.

visibleItems, hiddenItems, and itemOrder affect only the built-in toolbar UI. They do not remove the corresponding imperative API from triggerToolbarAction().

The package surfaces re-export two helper constants:

  • VASSIST_TOOLBAR_ACTIONS for the triggerToolbarAction() action IDs
  • VASSIST_TOOLBAR_ITEMS for the full built-in UI item list used by aiToolbar

VASSIST_TOOLBAR_ITEMS includes these UI-only item IDs in addition to the action IDs:

ts
"insert";
"undo";
"redo";

AI+ feature toggles still apply on top of this policy. If the user or host disables Translator, Summarizer, Rewriter, or Writer in AI+ settings/config, the corresponding built-in toolbar items are removed from the visible UI.

ts
aiToolbar: {
  showOnInputFocus: false,
  hiddenItems: ["add-to-chat", "image-identify-objects"],
  itemOrder: [
    "summarize-key-points",
    "translate",
    "write",
    "dictation",
  ],
}

setup ​

Controls the first-run setup wizard.

FieldTypeDefaultDescription
mode"full" | "deferred" | "hidden" | "custom""full"Setup wizard behavior
allowedStepsstring[][]Allowed step IDs when mode is "custom"
ModeBehavior
"full"Full setup wizard on first run
"deferred"Setup wizard stays hidden until the user explicitly starts
"hidden"No setup wizard
"custom"Show only the steps listed in allowedSteps

allowedSteps is only a good fit when you control the exact runtime build you ship. The current package surface does not export a stable public enum of setup-step IDs, so setup.mode: "custom" is version-coupled to the app build behind the embed.

For third-party integrations, prefer "full", "deferred", or "hidden" unless you also own the runtime version and its setup flow.

providers ​

Controls how AI, TTS, and STT provider configuration enters the runtime. The ai override includes current features such as decision-model settings and LLM parameter tuning.

FieldTypeDefaultDescription
mode"user-configurable" | "preconfigured" | "host-managed""user-configurable"Who owns provider setup and editing
aiDeepPartial<AIConfig> | nullnullAI config overrides
ttsDeepPartial<TTSConfig> | nullnullTTS config overrides
sttDeepPartial<STTConfig> | nullnullSTT config overrides
lockProviderSelectionbooleanmode !== "user-configurable"Prevent provider selection changes in the UI
ModeBehavior
"user-configurable"End users own provider setup and editing
"preconfigured"Host supplies defaults. Users can still edit unless policy locks them
"host-managed"Host owns provider setup and can treat the settings UI as informational or read-only

Important distinction:

  • providers.mode controls the UX and ownership model.
  • transport.mode controls who executes requests.

Anything you place inside providers.* is browser-visible config. If vendor credentials must stay off the client, use transport.mode: "host-bridge" and keep the real keys in your backend or native host.

ts
providers: {
  mode: "preconfigured",
  ai: {
    provider: "ollama",
    ollama: {
      endpoint: "http://localhost:11434",
      model: "llama3",
    },
  },
}

assets ​

Controls how 3D models, stages, motion packs, and other runtime assets resolve.

FieldTypeDefaultDescription
preset"default" | "none" | "host""default" when 3D is enabled, otherwise "none"Asset preset selection
assetBaseUrlstringundefinedBase URL prepended to relative asset paths
modelUrlstring | nullundefinedOverride the main 3D model
stageUrlstring | nullundefinedOverride the stage scene
motionPackstring | nullundefinedOverride the motion pack
resourceLoaderstring | ResourceLoaderAdapterLikeundefinedRegistered loader name or loader instance
PresetBehavior
"default"Use the bundled asset set
"none"Do not load 3D assets
"host"Only use the URLs the host explicitly supplies

assetBaseUrl only affects relative asset paths. Absolute URLs and blob: URLs pass through unchanged.

If you choose preset: "host", also provide one or more of these so the runtime can resolve what it needs:

  • modelUrl
  • stageUrl
  • motionPack
  • assetBaseUrl
  • resourceLoader

assets.resourceLoader ​

Use assets.resourceLoader when a simple base URL is not enough and the host needs custom path-resolution rules.

The value can be either a registered loader name or a loader instance:

ts
type ResourceLoaderSelection = string | ResourceLoaderAdapterLike;

interface ResourceLoaderAdapterLike {
  setMode?: (isExtension: boolean) => void;
  getURL: (path: string) => string;
  getURLAsync: (path: string) => Promise<string>;
  getModelURL: (filename: string) => string;
  getAnimationURL: (filename: string) => string;
  getTextureURL: (filename: string) => string;
  getPrivateTestURL: (type: string, filename: string) => string;
  isExtensionMode: () => boolean;
  loadJSON: <T = Record<string, unknown>>(path: string) => Promise<T>;
  loadText: (path: string) => Promise<string>;
  loadBinary: (path: string) => Promise<ArrayBuffer>;
  preloadResources: (paths: string[]) => Promise<ArrayBuffer[]>;
}

Register loaders at app startup through the package re-exports, then reference them by name in config:

ts
registerResourceLoader("cdn", loader);

assets: {
  resourceLoader: "cdn",
}

storage ​

Controls how chat history, settings, and other persistent state are stored.

FieldTypeDefaultDescription
mode"default" | "namespaced" | "memory" | "host""default"Storage mode
namespacestringundefinedNamespace prefix when mode is "namespaced"
adapterstring | StorageAdapterLikeundefinedRegistered adapter name or adapter instance when mode is "host"
ModeBehavior
"default"Default IndexedDB-backed storage
"namespaced"Default storage with a namespace prefix
"memory"In-memory only
"host"Delegate storage to a host-supplied adapter

storage.adapter ​

Use storage.mode: "host" when the host already owns persistence or when multiple embeds need to share a custom storage layer.

adapter accepts either a registered adapter name or a StorageAdapterLike instance.

Supported storage tables:

ts
"config";
"settings";
"cache";
"chat";
"files";
"sessions";
"data";

Adapter contract:

ts
interface StorageAdapterLike {
  get<T = unknown>(
    table: StorageTableName,
    key: string,
  ): Promise<T | StorageRecord | undefined>;
  getRecord(
    table: StorageTableName,
    key: string,
  ): Promise<StorageRecord | undefined>;
  set<T>(
    table: StorageTableName,
    key: string,
    value: T,
    metadata?: StorageMetadata,
  ): Promise<boolean>;
  remove(table: StorageTableName, key: string): Promise<boolean>;
  exists(table: StorageTableName, key: string): Promise<boolean>;
  getMultiple<T = unknown>(
    table: StorageTableName,
    keys: string[],
  ): Promise<Record<string, T | undefined>>;
  setMultiple<T>(
    table: StorageTableName,
    items: Record<string, T>,
  ): Promise<boolean>;
  clear(table: StorageTableName): Promise<boolean>;
  query(
    table: StorageTableName,
    filter: StorageRecord,
  ): Promise<StorageRecord[]>;
  getAll(table: StorageTableName): Promise<StorageRecord[]>;
  count(table: StorageTableName): Promise<number>;
  cleanupExpiredCache(): Promise<number>;
  getStats(): Promise<StorageStats>;
  isDatabaseReady?(): Promise<boolean>;
}

Register adapters at app startup through the package re-exports, then reference them by name in config:

ts
registerStorageAdapter("session", adapter);

storage: {
  mode: "host",
  adapter: "session",
}

theme ​

Controls the visual appearance of the assistant UI.

FieldTypeDefaultDescription
mode"adaptive" | "light" | "dark""adaptive"Color scheme
surfaceStyle"glass" | "flat""glass"Surface presentation
fontFamilystring"system-ui, Avenir, Helvetica, Arial, sans-serif"Base UI font stack
monoFontFamilystring"ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", \"Courier New\", monospace"Monospace font stack used by code-like surfaces
tokensVAssistThemeTokens{}Color token overrides for the active mode
inverseTokensVAssistThemeTokens{}Color token overrides for the inverse mode
effectsVAssistThemeEffectssee belowVisual effects configuration

Custom font loading is host-owned. If you set theme.fontFamily or theme.monoFontFamily, load the corresponding font yourself with your own CSS, asset pipeline, or a provider such as Google Fonts.

VAssistThemeTokens ​

Supported token keys:

ts
surfaceBase;
surfaceElevated;
surfaceInteractive;
surfaceOverlay;
surfaceHighlight;
textPrimary;
textSecondary;
textMuted;
borderColor;
borderStrongColor;
accentColor;
accentTextColor;
shadowColor;
inputPlaceholderColor;
focusRingColor;
statusError;
statusSuccess;
statusWarning;

effects ​

FieldTypeDefaultDescription
enableBackdropBlurbooleantrueEnable blur on glass surfaces
enableSurfaceShadowsbooleantrueEnable box shadows
enableAmbientOverlaybooleantrueEnable the ambient background overlay
backdropBlurPxnumber16Blur radius in pixels, clamped to >= 0

transport ​

Controls how AI, TTS, and STT requests are executed. It also defines the host callback used by the Decision API settings connection check.

FieldTypeDefaultDescription
mode"builtin" | "openai-compatible" | "custom" | "host-bridge""builtin" unless a bridge is presentTransport strategy
bridgeVAssistProviderBridgeundefinedHost-owned provider bridge implementation
xrPairingUrlstringundefinedOne-use desktop pairing URL, consumed before storage and providers initialize. Treat it as an ephemeral credential. Do not persist or log it.
ModeRuntime behavior
"builtin"Use the runtime's normal browser-side provider flow
"host-bridge"Delegate provider operations to transport.bridge
"openai-compatible"Preserved in normalized config, but does not add transport behavior by itself
"custom"Preserved in normalized config, but does not add transport behavior by itself

If you provide transport.bridge and omit transport.mode, normalization resolves the mode to "host-bridge" automatically.

transport.bridge.ai ​

MethodRequiredNotes
sendMessage({ messages, options, signal, onStream })YesUsed for both streaming and non-streaming message generation
configure(config)NoCalled when host-managed config changes
isConfigured()NoIf omitted, the runtime assumes AI is configured
getCurrentProvider()NoReturn a plain string or null synchronously in the current runtime
listModels(config)NoPowers remote model listing in the settings UI
testConnection()NoPowers provider connection tests
abortRequest()NoUsed when the user stops generation

transport.bridge.tts ​

MethodRequiredNotes
generateSpeech({ text, generateLipSync })YesReturn audio as Blob, ArrayBuffer, Uint8Array, or number[]. Optional mimeType and bvmdUrl are supported
configure(config)NoCalled when host-managed config changes
isConfigured()NoIf omitted, the runtime assumes TTS is configured
getCurrentProvider()NoReturn a plain string or null synchronously in the current runtime
testConnection({ text })NoPowers provider connection tests

The host bridge only generates audio. Playback, queueing, and lip-sync scheduling remain in the browser runtime.

transport.bridge.stt ​

MethodRequiredNotes
transcribeAudio({ audio, mimeType })YesReceives captured audio bytes and MIME type
configure(config)NoCalled when host-managed config changes
isConfigured()NoIf omitted, the runtime assumes STT is configured
testRecording({ duration, deviceId })NoPart of the exported bridge type, but the current built-in STT test flow still records locally and then calls transcribeAudio

The current runtime still records microphone audio in the browser, then passes the bytes to stt.transcribeAudio.

transport.bridge.decision ​

Select the "host" Decision API provider to keep endpoint credentials in the embedding host. The host bridge must implement decide(). The built-in connection check calls testConnection() when supplied, or sends a small test request through decide() otherwise. listModels() is optional:

ts
transport: {
  mode: "host-bridge",
  bridge: {
    decision: {
      async testConnection() {
        return checkMyDecisionBackend();
      },
      async decide(request) {
        return sendToMyDecisionBackend(request);
      },
    },
  },
}

The built-in Decision settings test uses this bridge when the provider is "host". Remote and desktop-local providers continue to use their configured HTTP endpoints. The current chat-generation flow does not call transport.bridge.decision. This bridge covers the Decision settings API.

ts
function toBytes(input: VAssistBinaryLike): Uint8Array {
  if (input instanceof Uint8Array) {
    return input;
  }
  if (input instanceof ArrayBuffer) {
    return new Uint8Array(input);
  }
  if (Array.isArray(input)) {
    return Uint8Array.from(input);
  }
  throw new Error("Expected ArrayBuffer, Uint8Array, or number[] in this host");
}

transport: {
  mode: "host-bridge",
  bridge: {
    ai: {
      getCurrentProvider: () => "host-backend",
      async sendMessage({ messages }) {
        const response = await fetch("/api/vassist/chat", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ messages }),
        });
        const data = await response.json();
        return {
          success: response.ok,
          response: typeof data.text === "string" ? data.text : null,
        };
      },
    },
    tts: {
      getCurrentProvider: () => "host-backend",
      async generateSpeech({ text }) {
        const response = await fetch("/api/vassist/tts", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ text }),
        });

        if (!response.ok) {
          return null;
        }

        return {
          audio: await response.arrayBuffer(),
          mimeType: response.headers.get("Content-Type") ?? "audio/mpeg",
        };
      },
    },
    stt: {
      async transcribeAudio({ audio, mimeType }) {
        const response = await fetch("/api/vassist/stt", {
          method: "POST",
          headers: {
            "Content-Type": mimeType ?? "application/octet-stream",
          },
          body: toBytes(audio),
        });

        const data = await response.json();
        return typeof data.text === "string" ? data.text : "";
      },
    },
  },
}

branding ​

Controls host-level labeling and icon overrides.

FieldTypeDefaultDescription
appNamestringundefinedBrand name stored in resolved config and snapshots
labelOverridesPartial<Record<VAssistLabelId, string>>undefinedOverride built-in labels by stable label ID
iconOverridesRecord<string, string>undefinedOverride built-in icons with URL strings keyed by icon name

appName is part of the public embed config, but visible built-in copy is currently customized primarily through labelOverrides.

For React hosts that need component-level icon control, prefer customizations.iconRenderers over URL-based iconOverrides.

Supported label IDs ​

ts
"chat.emptyState.title";
"chat.emptyState.description";
"chat.action.settings";
"chat.action.history";
"chat.action.stop";
"chat.action.new";
"chat.action.close";
"chat.action.hideCharacter";
"chat.action.showCharacter";
"chat.action.tempEnable";
"chat.action.tempDisable";
"chat.input.placeholder";
"chat.input.send";
"chat.input.close";
"chat.input.closeVoiceMode";
"history.title";
"history.searchPlaceholder";
"history.emptyState";
"settings.title";
"settings.managedByHost";
"toolbar.dictionary";
"toolbar.rewrite";
"toolbar.write";
"toolbar.dictate";
"toolbar.summarize";
"toolbar.translate";
"toolbar.imageDescribe";
"toolbar.addToChat";
"toolbar.insert";

hooks ​

Event callbacks for lifecycle and message activity.

HookSignatureFires when
onReady() => voidThe embed is initialized and ready
onOpen() => voidThe assistant opens
onClose() => voidThe assistant closes
onRequireSetup() => voidThe user needs provider setup before continuing
onMessage(payload: VAssistMessageEventPayload) => voidAny message is added
onMessageSent(payload: VAssistMessageEventPayload) => voidA user message is sent
onMessageReceived(payload: VAssistMessageEventPayload) => voidAn assistant message is received

VAssistMessageEventPayload ​

FieldTypeDescription
messageIdstringMessage ID
rolestringMessage role
contentstringMessage text
imagesstring[]Attached image data URLs
audiosstring[]Attached audio data URLs

VAssistRuntimeSnapshot ​

Returned by VAssistEmbedElementHandle.getRuntimeSnapshot() and window.VAssistEmbed.getRuntimeSnapshot().

FieldTypeDescription
hostIdstringStable host ID for the mounted instance
shellModeVAssistShellModeResolved shell mode
draftstringCurrent draft input text
currentChatIdstring | nullActive conversation ID
isTempChatbooleanWhether the current conversation is temporary
isProcessingbooleanWhether the assistant is currently generating
isSpeakingbooleanWhether TTS playback is active
isVoiceModebooleanWhether voice mode is active
pendingDropDatabooleanWhether host-supplied drop data is queued for the input
panelsobjectOpen-state snapshot for chat input, chat container, settings, and history
messagesVAssistRuntimeSnapshotMessage[]Current in-memory message list
embedConfigResolvedVAssistEmbedConfigFully normalized config for this host
uiConfigUIConfigCurrent UI config-store state
aiConfigAIConfigCurrent AI config-store state
ttsConfigTTSConfigCurrent TTS config-store state
sttConfigSTTConfigCurrent STT config-store state

snapshot.panels ​

FieldTypeDescription
chatInputOpenbooleanWhether the chat input is open
chatContainerOpenbooleanWhether the main chat container is open
settingsOpenbooleanWhether settings are open
historyOpenbooleanWhether history is open

VAssistRuntimeSnapshotMessage ​

FieldTypeDescription
idstringRuntime message ID
rolestringMessage role
contentstringMessage text
imagesstring[]Attached image data URLs
audiosstring[]Attached audio data URLs

Full Config Example ​

ts
function toBytes(input: VAssistBinaryLike): Uint8Array {
  if (input instanceof Uint8Array) {
    return input;
  }
  if (input instanceof ArrayBuffer) {
    return new Uint8Array(input);
  }
  if (Array.isArray(input)) {
    return Uint8Array.from(input);
  }
  throw new Error("Expected ArrayBuffer, Uint8Array, or number[] in this host");
}

const bridge: VAssistProviderBridge = {
  ai: {
    getCurrentProvider: () => "host-backend",
    async sendMessage({ messages }: { messages: unknown[] }) {
      const response = await fetch("/api/vassist/chat", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ messages }),
      });
      const data = await response.json();
      return {
        success: response.ok,
        response: typeof data.text === "string" ? data.text : null,
      };
    },
  },
  tts: {
    getCurrentProvider: () => "host-backend",
    async generateSpeech({ text }) {
      const response = await fetch("/api/vassist/tts", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ text }),
      });

      if (!response.ok) {
        return null;
      }

      return {
        audio: await response.arrayBuffer(),
        mimeType: response.headers.get("Content-Type") ?? "audio/mpeg",
      };
    },
  },
  stt: {
    async transcribeAudio({ audio, mimeType }) {
      const response = await fetch("/api/vassist/stt", {
        method: "POST",
        headers: {
          "Content-Type": mimeType ?? "application/octet-stream",
        },
        body: toBytes(audio),
      });

      const data = await response.json();
      return typeof data.text === "string" ? data.text : "";
    },
  },
};

const config: VAssistEmbedConfig = {
  mount: {
    target: document.querySelector("#assistant-slot"),
    hostId: "my-assistant",
    runtimeIsolation: "shadow-root",
    portalContainers: {
      popovers: "#assistant-popovers",
      canvas: document.body,
    },
  },
  shell: {
    mode: "full",
    deferSetupUntilStarted: true,
  },
  features: {
    liveAssistant3d: false,
    screenShare: false,
  },
  settings: {
    policy: {
      readOnly: ["llm", "tts", "stt"],
      hidden: ["ui.aiToolbar.showOnImageHover"],
    },
  },
  aiToolbar: {
    hiddenItems: ["add-to-chat"],
    itemOrder: ["summarize-key-points", "translate", "write"],
  },
  providers: {
    mode: "host-managed",
    lockProviderSelection: true,
  },
  assets: {
    assetBaseUrl: "https://cdn.example.com/vassist/",
  },
  storage: {
    mode: "namespaced",
    namespace: "my-app",
  },
  theme: {
    mode: "dark",
    surfaceStyle: "glass",
    tokens: {
      accentColor: "#1f6feb",
      accentTextColor: "#ffffff",
    },
  },
  transport: {
    mode: "host-bridge",
    bridge,
  },
  branding: {
    labelOverrides: {
      "settings.managedByHost": "Configured by Example Cloud",
    },
  },
  hooks: {
    onReady() {
      console.log("ready");
    },
    onMessage(payload) {
      console.log(payload.role, payload.content);
    },
  },
};