FAQ chips and the greeting bubble

Three things invite a visitor to start: the FAQ chips under the greeting, the greeting teaser on the closed launcher, and — on an app screen the owner configured — a proactive finding. The owner sets them up in the panel; a page can observe them and, for one of them, measure whether it is welcome.

In the panel: the chips are on Widget → Content → FAQ suggestion chips, and the teaser follows Widget → Launcher → Launcher attention (Widget settings).

FAQ chips

Up to 3 suggested questions (faqs, set per widget on the panel’s Content tab, localized to the page language) render as chips directly under the greeting in an empty conversation, on every device. A click sends that question exactly as if typed — the answer comes from the knowledge base, so there is no canned reply to maintain. The row leaves with the first message, a new conversation, or the greeting’s ✕. Parts: companion-faqs, companion-faq.

The greeting teaser

With launcherAttention not off (served as teaserEnabled) and a non-empty greeting, the closed launcher pops a small bubble after four seconds: typing dots for a beat, then the greeting typed like a real message, then up to 2 FAQ chips on a desktop viewport. Opening the chat after the teaser finished shows the greeting instantly rather than typing it again. Dismissing it, or opening the chat, is remembered for the session: up to 7 days, but forgotten after 45 minutes away. prefers-reduced-motion skips the dots and the typing.

Parts: teaser-group (carries [hidden]), teaser (the bubble, the click target), teaser-faqs, teaser-faq; tokens --sa-teaser-bg, --sa-teaser-color, --sa-teaser-radius, --sa-font-teaser, --sa-teaser-font-size. Events: shukai:teaser:shown, shukai:teaser:dismissed.

launcherAttention also sets the closed launcher’s attract animation: off is neither the animation nor the bubble; subtle and prominent differ in how much it moves. It shows until the first open.

The proactive finding

A second kind of teaser on the same bubble: on a screen whose source names a proactive tool, the widget sends a proactive_tick after 8 seconds on that screen, the server calls the owner’s endpoint with no model involved, and only on a non-empty result does a small model turn decide whether anything is worth saying. If so, the bubble shows one sentence, the character raises a hand, and the greeting timer will not overwrite it. No FAQ chips beside it: a finding is one specific thing.

• Armed only when there is something to arm: GET /widget/config says proactive: true when some screen the agent can see has a proactive tool and the plan allows it. Otherwise the widget starts no timer, watches no location and opens no socket.
• Per screen: the URL (plus a setContext route) is polled once a second, and a move re-arms the dwell. An open widget stops the question being asked at all.
• The cooldown is the server’s: the widget records { at, codes } per path in its prefs and sends the age as shown_ago_ms; the server applies the owner’s current window. Shortening the window in the panel takes effect at once.
• The click does what the server proposed: { kind: "navigate", url } goes through the ordinary cancelable shukai:action:navigate, so an SPA routes it; { kind: "ask", text } opens the chat and sends that question.

Three events let a host measure the dismissal rate — the real test of whether the raised hand is welcome — each with detail.codes naming the finding:

Shukai.on("suggestion:shown", (e) => track("finding_shown", e.detail.codes));
Shukai.on("suggestion:accepted", (e) => track("finding_clicked", e.detail.codes));
Shukai.on("suggestion:dismissed", (e) => track("finding_dismissed", e.detail.codes));

What a finding looks like from the owner’s endpoint is on Proactive findings.

What a page can change

teaserEnabled, teaserDelayMs, launcherAttention, faqs and greeting can all be overridden in ShukaiConfig; teaserDelayMs is served fixed at 4000 and a page value changes only that page. proactive is server-computed and a page override arms nothing the server will answer.