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 |
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 is exempt — a Welcome-launcher company is chat-only by design but renders the Welcome card.
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.
Configuration & options
| Setting | Field | Values / notes |
|---|---|---|
| Desktop style | companies.launcher_style | expended | middle | bubble | bar | welcome (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 | 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. - 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. - 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.