Widget Types & Launcher Styles
Audience: Sales · Support · QA · Engineering · Management · Where in app: Settings → Widget → Widget tab · Plan availability: All plans
The widget can render in one of several launcher styles — the shape and size of the thing a visitor first sees and clicks. The style is chosen per company (and can be overridden per page via page rules), separately for desktop and mobile. Different shapes serve different goals: a minimal bubble for low footprint, a large card for high-conversion landing pages, a horizontal bar for a single strong call-to-action, and so on.
What it does
The launcher style controls:
- The visual form of the closed/idle launcher.
- Which channel buttons (chat / video / audio) are advertised on the launcher surface.
- The size and animation of the iframe as the visitor opens chat or a call.
- Mobile vs desktop presentation (a separate style can be set for each).
How it works
The admin picks a style in the Widget tab. It is stored on companies.launcher_style (desktop) and companies.mobile_launcher_style (mobile). At load, the widget maps the stored backend value to an internal widget type and renders the matching component. The backend uses older internal names; the dashboard shows friendly names.
Available launcher styles
| Dashboard name | Backend launcher_style | Internal widget type | What it looks like | Best for |
|---|---|---|---|---|
| Ultimate | expended | ultimate | Large card with agent photo + video preview + CTA | High-conversion landing pages |
| Smart | middle | smart | Mid-size card with chat preview | Sites wanting more visibility |
| Bubble | bubble | bubble | Floating circular icon, bottom corner | Minimal footprint (common default) |
| Bar | bar | bar | Horizontal input bar at top/bottom | Single-channel emphasis ("Chat with us") |
| Welcome | welcome | welcome | Pill that expands to a card with Schedule + Ask CTAs | Auto-engaging visitors, booking-led |
| Chat Pill | (derived) | chat-pill | Slim pill-shaped chat-only launcher | Chat-only companies |
| Retro IM | retro | retro | Bubble launcher → 2003-messenger conversation window, calls + booking inside | Playful brands; see Retro IM |
Mapping notes (from
mapLauncherStyleToWidgetTypein the store): the legacyiconstyle now falls back to Smart; a "Mini" style was removed. Chat Pill is not a directly selectable style in the picker — it is the form the widget is forced into for chat-only companies (see below). The Welcome style renders its own card, never the chat pill.
Mobile vs desktop
mobile_launcher_style is applied when the widget detects a mobile device; it falls back to launcher_style if unset. Welcome wins on both devices: if Welcome is configured for either desktop or mobile, the widget uses Welcome everywhere, because Welcome carries its own chat-only-equivalent UX.
Chat-only override
If a company allows chat but disables both video and audio (communication_options: allow_chat !== false, allow_video_call === false, allow_audio_call === false), the widget overrides the chosen style to the slim chat-pill, regardless of launcher_style. This prevents the launcher from advertising call buttons the company can't honor. A store-level watcher enforces this on every code path that reassigns the widget type. Welcome and Retro IM are exempt — a Welcome-launcher company is chat-only by design but renders the Welcome card; Retro just hides its own call buttons. In the dashboard, clicking Chat Only while a device is on Retro switches that device to Ultimate (desktop) / Smart (mobile), as it does for Welcome.
Channels (what buttons the launcher exposes)
Each style respects companies.communication_options:
| Field | Effect |
|---|---|
allow_chat | Show chat button + label chat_label |
allow_video_call | Show video button + label video_call_label |
allow_audio_call | Show audio button + label audio_call_label |
chat_label / video_call_label / audio_call_label | Button labels |
take_phone_number_before_call | Require a phone-number form before a call can start |
Online vs offline messaging
The launcher swaps copy based on working-hours state (see Working Hours):
- Online:
online_title_text+online_title_text_sub_heading. - Offline:
offline_title_text+offline_title_text_sub_heading. Chat still works as an email fallback.
Retro IM (2026-10)
Widget eb102a0 / a3b8ca7 / 9fb5a01, backend e18577763 / 728d00879 / c934275ee, frontend cea38e05 / 5412d6ba.
- Components:
widget/src/components/retro/—RetroIM.vue(launcher; the "has just signed in" toast was removed in39648eb, 2026-10-20; since9fb5a01the launcher is the standardBubbleWidgetwithonLaunch/colorsprops, coloured by the skin viaskinLauncherColors, in a 120×130 box 20px from the corner),RetroWindows.vue(conversation window: toolbar Video Call / Voice Call / Book a Time / Nudge, emoji, Nudge + KNOCK!, file send, mute sounds, minimise/maximise),RetroCallStage.vue(call half: status/timer/meter, Mute, Camera, Flip, Settings, Schedule, Type instead, Products, Links, call-me form),RetroAudioSettings.vue,useRetroAgents.ts,retroIcons.ts(SKINS,customSkin,isModernSkin),retro.css,services/retroSound.ts(synthesised SFX). - Calls in the window: agent video/audio keep
VideoCallWidgetmounted out of sight as the call engine (engine-onlyprop); AI voice is driven from the store; call end returns to the retro window. Book a Time usescomposables/useCalendarBooking.ts(calendar slots, or the custom booking link). - View states:
retro,retro-chat,retro-chat-big(retro-toastis no longer entered; its loader size entry remains). The host loader (backend/public/widget.js) sizes them (launcher 260×76, window 660×620 / 880×740), clamps windows tomin(W,100vw) × min(H,100vh), sits retro iframes flush in the corner (the widget keeps its own gap/shadow room), goes full screen at ≤ 560px, and posts the host page width on init and resize (knockknock:viewport) for the widget's layout breakpoint. - Store: new messages bump
unreadCount(badge on the launcher) instead of opening chat; Retro never restores a savedkk_widget_type; chat-only never forces it to the pill. - Skins — see Styles & Appearance.
- Dev:
widget/retro-preview.html+src/dev/retroPreview.tsrender canned states for pixel checks.
Configuration & options
| Setting | Field | Values / notes |
|---|---|---|
| Desktop style | companies.launcher_style | expended | middle | bubble | bar | welcome | retro (also legacy icon) |
| Mobile style | companies.mobile_launcher_style | Same set; falls back to desktop style |
| Launcher side | companies.position | right (default) or left |
| Hide on mobile | companies.mobile_disable | When true, no widget on mobile |
| Global on/off | companies.visibility | Master switch |
| Channels | companies.communication_options.* | Buttons and labels (see table above) |
| Online/offline copy | online_title_text*, offline_title_text* | Launcher heading + subheading |
| Per-style colors | smart_widget_colors, extended_widget_colors, pill_widget_colors, welcome_widget_colors, bubble_widget, retro_skin/retro_custom_colors | See Styles & Appearance |
| Whitelabel footer | widget_whitelabel.is_enable / .text / .url | Replace "Powered by Knock Knock" |
Per-page override (page rules)
A widget page rule can change heading/subheading/video per URL. Note: the modern page-rule schema (widget_page_rules.rules[]) carries heading, sub_heading, offline_heading, and video_file_id — it does not itself switch launcher_style per page. (Older docs reference per-page launcher_style overrides; treat per-page style switching as verify.) See Page Rules.
Behaviors & edge cases
- Saved type restoration: the widget remembers the last type the visitor saw (
kk_widget_type) and may restore it across visits, but only within compatible transitions — e.g. Ultimate ↔ Bubble, Smart ↔ Bubble (Smart never restores to Ultimate). Bar, Chat Pill, and Welcome never restore to a different type. Since widget060b966the saved type is tied to the launcher it was saved under (kk_widget_type_launcher): when the company'slauncher_stylechanges, the saved type is dropped so the new style wins on the next load (it used to persist forever in the iframe's storage). - Welcome two-state launcher: Welcome has a collapsed pill and an expanded card; the expanded state is held in the store so it survives a chat round-trip (the component remounts when chat opens/closes).
- Bar on mobile: the bar opens chat as the Ultimate flow on mobile, then restores to the bar on close.
- Unknown/missing style: defaults to Ultimate.
- Default minimized state: Bubble resolves to the
minimizedview; other types resolve to their own named view.
Plan & limits
- All launcher styles are available on all plans (verify any per-tier gating of specific styles such as Welcome — not confirmed here).
- Whitelabel footer replacement depends on plan/agency tier — verify.
Technical implementation
- Store + mapping:
widget/src/stores/widget.ts—mapLauncherStyleToWidgetType(),isChatOnlyCompany(),setWidgetType()guard watcher,resolveViewState(). - Type definitions:
widget/src/types/company.ts—LauncherStyle,CommunicationOptions, per-style color interfaces. - Launcher components:
widget/src/components/widgets/—BubbleWidget.vue,SmartWidget.vue,UltimateWidget.vue,BarWidget.vue,WelcomeWidget.vue,ChatPillWidget.vue,AIVoiceWidget.vue; Retro IM underwidget/src/components/retro/. - Admin picker:
frontend/src/views/settings/widget/tabs/WidgetTab.vuewith previews infrontend/src/components/Widget/. - Legacy widget:
backend/public/widget.js+widgetController.js— older bubble/icon/mid/extended styles, still serving a share of installs. - See the engineering service page: /services/widget.