Конфігурація віджета в коді: window.ShukaiConfig

Для розробників, у коді: кожен ключ, який сторінка може задати у window.ShukaiConfig, звідки береться кожне значення за замовчуванням, і три речі про злиття, які дивують.

Конфігурація віджета складається з трьох шарів, останній перемагає: вбудовані значення за замовчуванням, конфігурація, яку власник зберіг у панелі (її віддає GET /widget/config), і те, що сторінка кладе у window.ShukaiConfig до завантаження скрипта.

У панелі: власник задає це на екрані налаштування віджета, без коду; ця сторінка — про те, як задати це кодом самої сторінки.

<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>

Три речі про злиття

Воно неглибоке. theme, launcher, strings і customCss замінюють значення з сервера повністю, а не зливаються з ним. Сторінка, що задає strings: { send: "Go" }, викидає всі інші локалізовані рядки, які мали б відвідувачі власника (відсутні ключі відкочуються до англійської); сторінка з launcher: { type: "none" } втрачає підпис і контейнер власника.
Недійсна position не дає віджету змонтуватися — вона перевіряється, і конструктор кидає помилку. Використовуйте точно один із чотирьох кутів.
Перевизначення зафіксованого на сервері ключа змінює лише сторінку. Шість ключів віддаються як фіксовані значення незалежно від рядка власника (showActionButtons, voiceInputPace, voiceInputAutosend, defaultModeDesktop, defaultModeMobile, teaserDelayMs). Сторінка може їх перевизначити, але сервер далі діє за своїм значенням: сховайте кнопки дій через showActionButtons: false — і сервер усе одно рахує кожне посилання ескалації як запропоноване.

Ключі, які сторінка може задати

Вигляд

Ключ	Тип	За замовчуванням	Сенс
`color`	CSS-колір	`#4f46e5`	основний колір; скорочення для `theme.primary`, який перемагає його
`position`	`bottom-right` · `bottom-left` · `top-right` · `top-left`	`bottom-right`	кут власника; перетягування відвідувачем перевизначає його для цього відвідувача
`theme`	`{ токен: значення }`	`{}`	токени теми без префікса `--sa-`; невідомі ігноруються, значення очищаються — Тема
`customCss`	рядок	`""`	сирий CSS, доданий останнім усередині shadow root
`strings`	`{ ключ: текст }`	48 англійських ключів	власний текст віджета; з сервера приходить локалізований, тож задавайте лише щоб навмисно змінити слово

Кнопка запуску й орб

Ключ	Тип	За замовчуванням	Сенс
`launcher.type`	`orb` · `image` · `none`	`orb`	анімований персонаж, зображення або нічого (headless) — Кнопка запуску і персонажі
`launcher.value`	URL	`""`	зображення для `type: "image"`; для `orb` ігнорується
`launcher.label`	рядок	`""`	видимий підпис робить кнопку «пігулкою»; також її `aria-label`
`launcher.container`	`elevated` · `flat` · `bare`	`elevated`	заливка з тінню, лише заливка або прозорий
`voiceCharacter`	`mic` · `fox` · `monster` · `robot2` · `kozak`	`robot2`	персонаж орба; невідомий id малює `robot2`
`voiceOrbColor`	CSS-колір	`""`	тіло орба; порожнє — іде за основним кольором. Намальований колір виводиться й обмежується, сірі лишаються сірими
`orbColours`	`{ частина: колір }`	—	частини персонажа; застосовуються до того, якого справді намальовано
`launcherAttention`	`off` · `subtle` · `prominent`	`subtle`	анімація привернення уваги закритої кнопки і привітальна підказка; `off` — ні те, ні те

Поведінка

Ключ	Тип	За замовчуванням	Сенс
`navigateEnabled`	boolean	`true`	віджет сам виконує `navigate` у межах origin, якщо сторінка не скасує подію
`pageActionsEnabled`	boolean	`false`	помічник може заповнювати й натискати на сторінці (з налаштування власника й тарифу)
`pageActionsSubmitPolicy`	`off` · `confirm` · `auto`	`off` у бандлі; `confirm` для нового віджета	згода на натискання, забезпечується сервером
`pageReadValues`	`off` · `marked` · `all`	`off`	які значення полів можуть покидати браузер
`teaserEnabled`	boolean	`false` у бандлі; з сервера виводиться з `launcherAttention`	привітальна бульбашка на закритій кнопці
`faqs`	string[]	`[]`	чіпи-підказки; компаньйон показує до 3, тизер до 2
`greeting`	рядок	`""`	перша репліка; без неї немає тизера
`handoffCollect` · `handoffAlways`	boolean	`false`	контактна форма в чаті; вхід «Зв’язатися з нами» в доку, коли за ним є ціль або форма
`aiLabel`	boolean	`false`	позначка «Асистент зі штучним інтелектом» над рядком підказки (`::part(companion-ai-label)`, рядок `companion.ai_label`); вмикає власник
`actionButtonTypes`	array	`["navigate"]`	для яких типів дій під відповіддю малюється кнопка; приходить із віджета власника

Де з’являється — лише показ; ключ публічний, тож це не контроль доступу

Ключ	Тип	За замовчуванням	Значення
`pageRule`	`all` · `except` · `only`	`all`	на всіх сторінках, усюди, крім `pagePatterns`, або лише на них
`pagePatterns`	string[]	`[]`	шляхи: `/login`, `{id}` — будь-яка одна частина (`/orders/{id}/receipt`), `` у кінці — сторінка й усе під нею (`/account/`); query не враховується
`signedInOnly`	boolean	`false`	показується лише після `Shukai.setUser(token)` — Ідентичність користувача

Шаблон називає сторінку, коли збігається зі шляхом адреси або з маршрутом, який ваша сторінка оголосила через Shukai.setContext({ route }), — так ці правила працюють і в застосунку з hash-маршрутизацією. Плейсхолдер — це ціла частина шляху (/orders/{id}, а не /orders/order-{id}), а шлях іншою абеткою пишеться так, як читається (/ціни). Рішення ухвалюється наново на кожній зміні маршруту.

Голос

Ключ	Тип	За замовчуванням	Сенс
`conversationModeEnabled`	boolean	`false`	мікрофон персонажа і голосові відповіді
`voiceInputEnabled`	boolean	`false`	мікрофон диктування в полі вводу
`voice`	`{ мова: { name } }`	`{}`	перевизначення голосу власником за мовами; читає сервер, обираючи голос

Ключі, які сторінці не варто задавати

Це з’єднання і списки з сервера. Їх перевизначення змушує віджет говорити не туди або втрачати те, що обчислив сервер.

agentBase, widgetKey, code, agentCode (з’єднання — з фрагмента); pageLang (виводиться з <html lang>); supportedLanguages, sttLanguages, sttAutonyms, handoffTargets (списки з сервера); pageRead, proactive (обчислюються сервером із джерел помічника); previewMode (лише прев’ю в панелі — вимикає дії на сторінці); voiceProvider (не ключ з 2026-10-05: єдиний голосовий рівень працює на сервері, і значення тут ігнорується).

Читання конфігурації з сервера

GET /widget/config?code=&lang= повертає конфігурацію власника в snake_case, локалізовану для lang; віджет зіставляє її з camelCase-ключами вище. Відповідь описано в Widget config. Прапорець active читається раніше за все і не перевизначається зі сторінки: неактивний віджет нічого не монтує.