Widget Styles & Appearance

Audience: Sales · Support · QA · Engineering · Management · Where in app: Settings → Widget → Colors and Style tabs · Plan availability: All plans

Almost everything a visitor sees on the widget is tunable from the dashboard: message bubble colors, button colors, header/footer, the call screen background, the launcher copy, and the questions asked before chat starts. Settings live mostly on companies.widget_design plus several top-level and per-style color objects. Changes take effect on the next visitor session — no redeploy.

What it does

• Sets the color palette for messages, buttons, header, footer, and call screen.
• Provides per-launcher-style palettes (smart, ultimate/extended, pill, welcome, bubble).
• Controls visitor-facing copy (launcher headings, button labels).
• Defines the pre-chat questions (online and offline) and contact-info questions.
• Configures the whitelabel "Powered by" footer.

How it works

The admin edits colors and copy in the Colors and Style tabs; values are saved onto the company document and fetched by the widget at load. A live mini-preview in the dashboard renders changes as you type.

Core color schema (companies.widget_design)

The modern schema is nested (see WidgetDesign in types/company.ts):

Group	Fields
message.receiver	background_color, text_color (visitor's bubble)
message.sender	background_color, text_color (agent / AI bubble)
header	background_color, text_color
footer	background_color, text_color, hide_knock_logo, hide_powered_by
btn_video_call / btn_audio_call / btn_chat	background_color, text_color
btn_down_arrow	background_color, text_color, arrow_position
btn_submit_phone	background_color, text_color
sticky_widget	background_color, icon_and_text_color
call_background	background_color, background_image
live_tag	background_color, text_color, enabled
bubble_widget	background_color, text_color

An older flat schema (receiver_message_bg, sender_message_bg, button_bg, header_bg, footer_bg, call_background_color, chatbot_auto_trigger_bg, etc.) is referenced in legacy material. The modern bundle uses the nested form above; expect both shapes in the wild depending on the company's age and which codebase serves it.

Per-launcher-style palettes

Each launcher style has its own optional color object so styles can be themed independently:

Style	Object	Notable fields
Smart	smart_widget_colors	background_color, text_color
Ultimate (extended)	extended_widget_colors	video_btn_color/_icon, audio_btn_color/_icon, chat_btn_color/_icon, booking_btn_color/_icon, icon_and_text_color, live_tag_bg, live_tag_text
Chat Pill	pill_widget_colors	gradient_start, gradient_end, text_color
Welcome	welcome_widget_colors	pill_gradient_start/_end, pill_text_color, chat_btn_color/_icon, call_btn_color/_icon, schedule_btn_color/_icon/_label, show_schedule_btn, icon_and_text_color, footer_background, footer_text_color
Bubble	bubble_widget	background_color, text_color

Top-level color / layout fields

Field	What
companies.primary_color	Highlights (links, ticks, accents)
companies.secondary_color	Secondary accent
companies.position	Launcher side: right (default) or left
companies.chat_widget_type	extend or small — chat window size

Visitor-facing copy

Field	Where it shows
launcher_text	Bubble launcher CTA label (default "Let's Talk"; empty → i18n launcher.letsTalk)
online_title_text / _sub_heading	Launcher header/subheading during working hours
offline_title_text / _sub_heading	Launcher outside working hours
communication_options.chat_label	Chat button label
communication_options.video_call_label	Video button label
communication_options.audio_call_label	Audio button label
agent_connection_request_text	Text shown while connecting to an agent
privacy_policy_text / privacy_policy_url	Privacy link in the widget

Chatbot / pre-chat questions

Field	What
chatbot_online_questions[]	Questions asked before connecting to a live agent (online)
chatbot_online_message	Greeting when online
chatbot_online_after_questions_message	Confirmation after answers submitted
chatbot_offline_questions[]	Equivalent set for offline (email-fallback flow)
chatbot_offline_message / _after_questions_message	Equivalent offline copy

Contact-information questions

companies.contact_information_questions controls what's asked before chat or call. In the modern schema each is { enabled: boolean, question: string }:

name:  { enabled, question }
email: { enabled, question }
phone: { enabled, question }

Plus take_phone_number_before_call — phone becomes mandatory before a call when true.

Call screen background

Specific to the call interface:

• widget_design.call_background.background_color / .background_image
• For the call auto-trigger popup: call_auto_trigger.call_background.*, call_auto_trigger.text_color, and call_auto_trigger.auto_connect_video_file (FileModel id, uploaded via Default Videos).
• Per AI call interface: ai_calling.call_interface (background_color, controller_bar_color, icon_color, hide_connecting_steps, hide_latest_message, avatar_image, agent_name).

Whitelabel footer

widget_whitelabel.is_enable: boolean
widget_whitelabel.text: string   // "Powered by ..."
widget_whitelabel.url:  string   // link target

When is_enable is false, the default "Powered by Knock Knock" appears. The nested widget_design.footer.hide_knock_logo / hide_powered_by flags can also suppress the default branding. Availability depends on plan/agency.

Mobile vs desktop

• mobile_disable: true — hide on mobile entirely.
• mobile_launcher_style — a separate launcher style on mobile (falls back to desktop style).

Configuration & options

All settings above are edited in Settings → Widget, split across tabs:

Tab	Covers
Widget	Launcher style (desktop/mobile), online/offline titles
Colors	widget_design.*, per-style palettes, primary_color, theme presets
Style	Layout/position, chat window size, footer/whitelabel
Channels	Channel toggles + labels, pre-chat/contact questions

The Colors tab ships theme presets (Default, Purple, Warm, Ocean, Dark, Green) as quick starting points.

Behaviors & edge cases

• Two schemas coexist (nested widget_design.* vs older flat fields). When debugging a color that "won't change," check which schema the serving codebase (modern vs legacy) reads.
• Per-style palettes override core for that launcher — e.g. Welcome's button colors come from welcome_widget_colors, not widget_design.btn_*.
• Changes are session-fresh: config is fetched per visitor load, so a hard refresh of the customer's site shows new colors with no redeploy.
• Contrast: receiver/sender bubble colors should meet WCAG-AA against the chat window background — there is no automatic contrast guard.
• Position left is supported but unusual; useful when the site already has a right-side cart drawer.
• Whitelabel/branding hide flags depend on plan and may be ignored on tiers that don't allow branding removal — verify.

Plan & limits

• Color and copy customization is available on all plans.
• Whitelabel footer replacement and branding-hide flags depend on plan/agency tier — verify against the plan matrix.

Technical implementation

• Types: widget/src/types/company.ts — WidgetDesign, SmartWidgetColors, ExtendedWidgetColors, PillWidgetColors, WelcomeWidgetColors, BubbleWidgetColors, CallInterface, ContactInformationQuestions.
• Store color mapping: widget/src/stores/widget.ts — WidgetColors / WidgetSettings and the mapping from company config to runtime colors.
• Styles (SCSS): widget/src/assets/scss/ — per-component partials (_chat-widget.scss, _bubble-widget.scss, _smart-widget.scss, _ultimate-widget.scss, _ai-voice-widget.scss, _video-call-widget.scss).
• Admin UI: frontend/src/views/settings/widget/tabs/ColorsTab.vue, StyleTab.vue, ChannelsTab.vue, ColorInput.vue.
• Nox: can report "what colors are configured?", "what does the offline message say?", and "is whitelabel on?" by reading widget_design and friends. It cannot apply new colors — an admin edits them in the dashboard.
• See the engineering service page: /services/widget.

Related

• Widget Types & Launcher Styles
• Working Hours
• Page Rules
• Installation