Diese Seite erscheint auf Englisch und Ukrainisch; unten steht die englische Fassung.

Install the widget on your site: one script tag

For developers, in code: the one script tag from the panel's Install tab, what each attribute means, and how to check it works.

The panel gives you the snippet on the widget’s Install tab. It is specific to your site (the key) and to one widget (the code), and it looks like this:

<script
  src="https://<widget host>/widget.js"
  data-key="wk_…"
  data-code="default"
  data-agent-base="https://<agent host>"
  async
></script>

Paste it before </body> on every page the assistant should be on — or into your site builder’s «custom code» box. That is the whole installation.

The attributes

Attribute	What it is
`src`	The widget bundle, served from our CDN. One file, loaded once, cached by the browser.
`data-key`	The site’s widget key. It is public by design and restricted server-side to the origins listed on the key — copy it anywhere, it only works on your own domains. One key covers every widget of the site.
`data-code`	Which widget of the site to load. The first widget is `default`. If the attribute is missing the bundle loads the site’s `default` widget and logs a warning in the console; on a site with several widgets, re-copy the snippet so the right one is pinned.
`data-agent-base`	The runtime the widget talks to: `GET /widget/config` for its appearance, `WS /ws` for the conversation, `/tts` and `/ws/stt` for voice.
`async`	Loads without blocking your page.

If data-key or data-agent-base is missing the widget warns and does nothing.

What loads

One bundle, one host element. The widget appends <div id="sa-widget"> to body and renders everything inside an open shadow root, so your page’s CSS cannot touch it by accident and its CSS cannot touch your page. The host element is where you set theme tokens from your own CSS (Theming); it sits above everything (z-index: 2147483000).

<html lang> is an input: it decides the language of the widget’s own text (buttons, labels, the greeting), hints the reply language of the first message, and switches the interface to right-to-left for Arabic, Hebrew and the other RTL languages (Languages and RTL).

Only one widget per page is supported: do not paste two snippets on one page. To show a different look on different pages, create a second widget in the panel and paste its snippet on those pages — the key is the same, the data-code differs.

Overriding the served configuration

Everything the owner set in the panel arrives from GET /widget/config. A page can override any of it before the script loads:

<script>
  window.ShukaiConfig = { color: "#059669", voiceCharacter: "fox" };
</script>
<script src="…/widget.js" data-key="…" data-code="…" data-agent-base="…" async></script>

The merge is shallow — see Configuration for the keys and the three things that surprise people.

Check that it works

Load the page. The launcher appears in the corner the owner chose.
Open the browser’s network tab: GET /widget/config answers 200 with the owner’s configuration.
Ask something the site answers. The answer carries a source link under it.

The widget logs nothing in either of the two cases below, so look at that request. If the corner is empty and it answered active: false, the site is out of credits or not on a plan: nothing mounted, and the page did nothing wrong. Shukai.ready still resolves and every method is a no-op until the plan is active again.

If it answered 403, the page’s origin is not on the key’s allowed-origins list: the launcher still appears with the built-in look, but every question is refused. Add the origin on the panel’s API keys screen.

If it answered 404, the site has no switched-on widget with the snippet’s data-code: it is switched off on its Install tab, deleted, or the code is mistyped. Nothing is shown, and this time the console says so in one line.

Where the assistant’s answers come from