Skip to main content

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 nameBackend launcher_styleInternal widget typeWhat it looks likeBest for
UltimateexpendedultimateLarge card with agent photo + video preview + CTAHigh-conversion landing pages
SmartmiddlesmartMid-size card with chat previewSites wanting more visibility
BubblebubblebubbleFloating circular icon, bottom cornerMinimal footprint (common default)
BarbarbarHorizontal input bar at top/bottomSingle-channel emphasis ("Chat with us")
WelcomewelcomewelcomePill that expands to a card with Schedule + Ask CTAsAuto-engaging visitors, booking-led
Chat Pill(derived)chat-pillSlim pill-shaped chat-only launcherChat-only companies
Retro IMretroretroBubble launcher → 2003-messenger conversation window, calls + booking insidePlayful brands; see Retro IM

Mapping notes (from mapLauncherStyleToWidgetType in the store): the legacy icon style 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:

FieldEffect
allow_chatShow chat button + label chat_label
allow_video_callShow video button + label video_call_label
allow_audio_callShow audio button + label audio_call_label
chat_label / video_call_label / audio_call_labelButton labels
take_phone_number_before_callRequire 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 in 39648eb, 2026-10-20; since 9fb5a01 the launcher is the standard BubbleWidget with onLaunch/colors props, coloured by the skin via skinLauncherColors, 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 VideoCallWidget mounted out of sight as the call engine (engine-only prop); AI voice is driven from the store; call end returns to the retro window. Book a Time uses composables/useCalendarBooking.ts (calendar slots, or the custom booking link).
  • View states: retro, retro-chat, retro-chat-big (retro-toast is 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 to min(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 saved kk_widget_type; chat-only never forces it to the pill.
  • Skins — see Styles & Appearance.
  • Dev: widget/retro-preview.html + src/dev/retroPreview.ts render canned states for pixel checks.

Configuration & options​

SettingFieldValues / notes
Desktop stylecompanies.launcher_styleexpended | middle | bubble | bar | welcome | retro (also legacy icon)
Mobile stylecompanies.mobile_launcher_styleSame set; falls back to desktop style
Launcher sidecompanies.positionright (default) or left
Hide on mobilecompanies.mobile_disableWhen true, no widget on mobile
Global on/offcompanies.visibilityMaster switch
Channelscompanies.communication_options.*Buttons and labels (see table above)
Online/offline copyonline_title_text*, offline_title_text*Launcher heading + subheading
Per-style colorssmart_widget_colors, extended_widget_colors, pill_widget_colors, welcome_widget_colors, bubble_widget, retro_skin/retro_custom_colorsSee Styles & Appearance
Whitelabel footerwidget_whitelabel.is_enable / .text / .urlReplace "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 widget 060b966 the saved type is tied to the launcher it was saved under (kk_widget_type_launcher): when the company's launcher_style changes, 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 minimized view; 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 under widget/src/components/retro/.
  • Admin picker: frontend/src/views/settings/widget/tabs/WidgetTab.vue with previews in frontend/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.