Widget JavaScript API: window.Shukai

For developers, in code: window.Shukai — every method, which calls are queued until mount and which are state, and how sending a message, signing out and page actions work.

window.Shukai is installed the moment the script runs. Calls made before the widget has mounted are queued and replayed in order, so you never have to wait for it:

Shukai.ready.then(() => {}); // resolves to the API once mounted
Shukai.open();
Shukai.sendMessage("Do you deliver on Saturdays?");

Methods

Method	Returns	Kind	What it does
`ready`	`Promise<api>`	—	resolves once mounted — also when the widget is inactive (then every method is a no-op) or hidden on this page (it mounts when first shown)
`hide()` · `show()` · `isHidden()`	api · api · boolean	state, this page	take the assistant off the page and bring it back; an open chat closes, the conversation is kept; `show()` never overrides the owner’s page rule or signed-in-only
`open()` · `close()` · `toggle()`	—	queued	open or close the companion; `open()` is the only entrance for a headless launcher
`isOpen()`	boolean	immediate	`false` before mount
`newConversation()`	—	queued	start a fresh conversation; the old one stays in the device’s history
`sendMessage(text)`	—	queued	opens, then sends. Opens in text chat unless the visitor’s remembered mode is a voice conversation, so the answer is not spoken
`speak(text)`	—	queued	reads the text aloud; a no-op unless conversation mode is on and audio is unlocked
`stopSpeaking()`	—	queued	the visitor saying «be quiet»: the rest of that answer stays silent, and in a conversation the mic reopens
`startListening()` · `stopListening()`	—	queued	inside a live conversation, a turn; otherwise a dictation into the composer — a no-op when dictation is off, even with conversation mode on
`setPageActions(on)`	—	queued, never stored	page actions off or on for this page load only; cannot enable what the owner disabled; turning it off also stops the assistant reading and scrolling the page
`setContext({ route, params })`	api	state	the declared screen for hash routing or a shared path; call on every route change — Single-page apps
`getContext()`	`{ route, params }`	state	the last declared context
`setUser(token)` · `clearUser()` · `getUser()`	api · api · string	state, memory only	the logged-in user’s token, relayed as `{{user}}` — User identity
`clearHistory()`	—	queued	wipes every conversation on this device and the remembered mode; ends a live conversation; aborts a dictation; empties the composer
`on(name, fn)` · `off(name, fn)`	api	—	thin wrappers over `window.addEventListener`; accept `"open"` or `"shukai:open"`

Queued calls run after mount in the order made. State calls are read afresh on every message, so the newest value wins and a call before mount is fine.

While the widget is hidden on the page — by the owner’s page rule, by «only to signed-in users» before setUser, or by your own hide() — open(), toggle(), sendMessage(), speak() and startListening() do nothing and are not replayed later; the console says once which of the three hides it. Everything else still works, clearHistory() included.

There is no expand, collapse or presentation: calling one throws a TypeError. There is no converse(text) yet — a method that opens straight into a voice conversation and speaks the answer is planned; today sendMessage gives the same answer and action in text.

Sending, signing out and page actions

sendMessage sends the text as the visitor’s message. It opens the widget and sends it; the answer appears in the chat, and is also read aloud when the visitor is already in a voice conversation. A voice conversation starts when the visitor presses the assistant’s microphone — it is there when the owner has voice conversations switched on and the browser can use a microphone — so to invite one, open the widget with open().

Signing out: clearUser and clearHistory. clearUser() forgets the user’s token, so the assistant stops fetching their data. clearHistory() forgets the conversations kept on this device — up to seven days of them. At sign-out on a computer other people may use, call both. When a session simply expires, clearUser() alone is enough: it is still the same person at the screen.

setPageActions applies to the current page load. Page actions are on at every load where the widget works with the page; setPageActions(false) switches them off for this load — the assistant then neither fills, presses, reads nor scrolls the page — and setPageActions(true) switches them back on. Call it on each load where you want them off.

Lifecycle

Shukai.on("open", () => analytics.track("assistant_opened"));
Shukai.on("message:received", (e) => console.log(e.detail.text, e.detail.sources));
Shukai.on("suggestion:dismissed", (e) => console.log("dismissed finding", e.detail.codes));

Every event the widget emits is on Events.