Widget configuration in code: window.ShukaiConfig

The widget’s configuration is assembled in three layers, last one wins: the built-in defaults, the configuration the owner saved in the panel (served by GET /widget/config), and whatever the page puts in window.ShukaiConfig before the script loads.

In the panel: an owner sets these on the Widget settings screen, without code; this page is for setting them from the page’s own code.

<script>
  window.ShukaiConfig = {
    color: "#059669",
    position: "bottom-left",
    voiceCharacter: "fox",
    theme: { "launcher-radius": "16px" },
  };
</script>
<script src="…/widget.js" data-key="…" data-code="…" data-agent-base="…" async></script>

Three things about the merge

1. It is shallow. theme, launcher, strings and customCss each replace the served value whole, not merge into it. A page that sets strings: { send: "Go" } throws away every other localized string the owner’s visitors would have had (missing keys fall back to English); a page that sets launcher: { type: "none" } drops the owner’s label and container.
2. An invalid position stops the widget mounting — it is validated, and the constructor throws. Use one of the four corners exactly.
3. A host override of a server-fixed key changes only the page. Six keys are served as fixed values whatever the owner’s row holds (showActionButtons, voiceInputPace, voiceInputAutosend, defaultModeDesktop, defaultModeMobile, teaserDelayMs). A page may still override them, but the server keeps acting on its own value: hide the action buttons with showActionButtons: false and the server still counts every escalation link as offered.

Keys a page may set

Appearance

Launcher and orb

Behaviour

Where it appears — display only; the key is public, so these are not access control

A pattern names a page when it matches the address’s path or the route your page declared with Shukai.setContext({ route }) — which is how a hash-routed app uses these too. A placeholder is a whole part of the path (/orders/{id}, not /orders/order-{id}), and a path in another alphabet is written as you read it (/ціни). The verdict is taken again on every route change.

Voice

Keys a page should not set

These are the connection and served-only lists. Overriding them makes the widget talk to the wrong place or lose what the server computed.

agentBase, widgetKey, code, agentCode (the connection — come from the snippet); pageLang (derived from <html lang>); supportedLanguages, sttLanguages, sttAutonyms, handoffTargets (served lists); pageRead, proactive (server-computed from the agent’s sources); previewMode (the panel’s preview only — it switches page actions off); voiceProvider (not a key since 2026-10-05: the one voice tier runs on the server, and a value here is ignored).

Reading the served configuration

GET /widget/config?code=&lang= returns the owner’s configuration in snake_case, localized for lang; the widget maps it to the camelCase keys above. The response is on Widget config. The active flag is read before anything else and cannot be overridden from the page: an inactive widget mounts nothing.