Skip to main content

Widget Runtime API

The public global is window.ChatbotWidget. The standard bootstrap creates it after loading the widget bundle and calls init() with authenticated settings. Methods use chatbot-root when a target is omitted.

Command results​

Context and visibility commands return:

type CommandResult =
  | { ok: true; contextRevision?: number }
  | {
      ok: false;
      reason: "not_initialized" | "invalid_context" | "inline";
      issues?: ContextIssue[];
    };

invalid_context is non-mutating. not_initialized means the selected target has no runtime controller. inline means a close request cannot apply.

init​

init(targetId?: string, config?: WidgetConfig): void

Mounts the widget, creating the target element when absent. The default target is chatbot-root. Calling it again for the same target reuses the React root and runtime controller, merges configuration through the rendered runtime, and preserves context and conversation state.

window.ChatbotWidget.init("chatbot-root", authenticatedSettings);

Host applications should normally let bootstrap.js perform this call because it obtains trusted settings first.

updateConfig​

updateConfig(targetId?: string, patch?: Partial<WidgetConfig>): void

Shallow-merges a patch into the stored configuration and rerenders the target. It can create the default target if none exists, but host-provided values do not replace server authentication or make untrusted settings trusted.

window.ChatbotWidget.updateConfig("chatbot-root", {defaultOpen: true});

getConfig​

getConfig(targetId?: string): Partial<WidgetConfig> | undefined

Returns the runtime's stored configuration for a target. It returns undefined when none exists. Treat the result as runtime state, not a secure credential store.

destroy​

destroy(targetId?: string): void

Unmounts the root, removes its configuration and controller, removes the target element, and clears window.solWidgetConfig.

window.ChatbotWidget.destroy("chatbot-root");

This affects the current page only. It does not delete the assistant or stored evidence.

setContext​

setContext(context: unknown): CommandResult
setContext(targetId: string, context: unknown): CommandResult

Validates and replaces the complete current context. An identical value keeps the existing revision. A changed valid value increments it. Invalid input is rejected without partially applying fields.

window.ChatbotWidget.setContext({
  surface: "documentation",
  contentId: "docs/embed-and-deployment",
});

See Add Contextual Help for the schema.

open​

open(options?: {context?: unknown; source?: "host" | "launcher"}): CommandResult
open(targetId: string, options?: OpenOptions): CommandResult

Optionally validates and applies replacement context, requests floating expansion, records the source (default host), and requests focus. It does not remount the widget or start a new conversation.

close​

close(targetId?: string): CommandResult

Requests that a floating widget collapse. It returns {ok: false, reason: "inline"} for inline placement and not_initialized for an unknown target.

Compatibility boundary​

Only the methods listed here are public. Controller subscription, telemetry, navigation, focus counters, and rendering internals are not public APIs. Existing optional-target overloads and the default chatbot-root are retained for compatibility.

For installation and security guidance, see Embed and Deploy the Widget.