Widget Customization

Widget Customization

Personalize the appearance of your chat widget to match your brand and website design.

Settings

All widget customization options are available at Settings → Channels → Web. Select your web channel and open the Appearance tab.

---

Theme Color

The theme color is applied consistently across the entire widget:

• Launcher button background
• Header bar background
• Send button color
• Link highlight color
• User message bubble background

Choose a color that matches your brand identity and ensures good contrast against white text.

---

Secondary Color

v1.6.11

An optional accent color applied to secondary UI elements such as highlights and icons. When not set, the secondary color is automatically derived by shifting the primary hue by 10°.

Default: Auto-derived from primary color (hue + 10°)

Format: 6-digit hex (#RRGGBB)

Via Dashboard: Set under Settings → Channels → Web → Customizer → Secondary Color.

Via Embed Code: Pass secondaryColor in the theme configuration:

<script>
  window.ClientaConfig = {
    botId: "YOUR_BOT_ID",
    widgetId: "YOUR_WIDGET_ID",
    theme: {
      secondaryColor: "#0062cc"
    }
  };
</script>

---

Welcome Message

The welcome message is the first text customers see when they open the widget. Keep it friendly and clearly explain what the bot can help with.

Examples:

1. “Hi! How can I help you today?”
2. “Welcome to Acme Support. Ask me anything about our products and services.”
3. “Hello! I’m here to help. What can I assist you with?”

---

Widget Position

Position	Setting Value	When to Use
Bottom-right	bottom-right (default)	Standard placement, works for most sites
Bottom-left	bottom-left	When right side conflicts with other elements

---

Avatar

v1.6.4

Display a custom avatar in the widget header and home screen by providing an image URL.

Via Dashboard: Set the avatar URL in Settings → Channels → Web → Customizer → Avatar URL.

Via Embed Code: Pass avatarUrl in the theme configuration:

<script>
  window.ClientaConfig = {
    botId: "YOUR_BOT_ID",
    widgetId: "YOUR_WIDGET_ID",
    theme: {
      avatarUrl: "https://example.com/your-logo.png"
    }
  };
</script>

Requirements:

• Must be an https:// URL (http, data:, and javascript: URLs are rejected for security)
• Recommended size: 128 × 128 pixels (square)
• Supported formats: PNG, JPG, WebP, SVG
• If the URL is invalid or the image fails to load, the default icon is displayed

---

Launcher Icon

v1.6.11

Replace the default chat bubble SVG with a custom icon on the launcher button.

Default: Built-in chat bubble SVG icon

Format: https:// URL to an image (http:// is rejected for security)

Recommended: 28 × 28 pixels, PNG or SVG with transparency

Via Dashboard: Set under Settings → Channels → Web → Customizer → Bubble Icon.

Via Embed Code: Pass bubbleIcon in the theme configuration:

<script>
  window.ClientaConfig = {
    botId: "YOUR_BOT_ID",
    widgetId: "YOUR_WIDGET_ID",
    theme: {
      bubbleIcon: "https://example.com/your-icon.png"
    }
  };
</script>

Requirements:

• Must use https:// (http:// and other protocols are rejected for security)
• If the URL fails to load, the default SVG icon is displayed automatically

---

Greeting Mode

v1.6.2

The greeting message supports three language modes. Go to Settings → Channels → Web → Customizer and look for the Greeting Mode section.

Static

The same greeting text is shown to every visitor regardless of language. This is the default mode.

Enter a single greeting in the text field. Example: “Hi! How can I help you today?”

Match Visitor (locale)

Show a different greeting for each language. The widget reads the visitor’s detected language and shows the matching greeting.

1. Select Match Visitor mode.
2. A field appears for each of the 15 supported locales.
3. Fill in the greeting text for each language you want to support.
4. Leave a locale’s field blank to fall back to the Static greeting for that language.

Example setup:

• Thai: “สวัสดีค่ะ! มีอะไรให้ช่วยไหม?”
• English: “Hi! How can I help you today?”
• Japanese: “こんにちは！何かお手伝いできますか？“

Org-Main

The greeting is always shown in the organization’s main response language, regardless of the visitor’s language. This mode reads the language set in AI Settings → Main Response Language.

Use Org-Main when your team operates in one language and you want all greetings to be consistent.

---

Language Selector

v1.6.2

The language selector adds a globe icon (🌐) to the widget header so visitors can explicitly choose their language. It is disabled by default.

To enable: In Settings → Channels → Web → Customizer, toggle Show Language Selector to ON.

When a visitor selects a language from the dropdown:

• All AI responses are locked to that language for the session
• The lock overrides auto-detection even if the visitor types in a different language
• The widget UI switches to the selected language

See Web Widget — Language Selector for the full behavior overview.

---

Default Language

v1.6.8

Set a default language for the widget so visitors see the UI in your preferred locale before any auto-detection occurs. Go to Settings → Channels → Web → Customizer → Default Language and select from the dropdown.

The language priority chain is:

1. Force This Language (AI Settings) — overrides everything when enabled
2. Visitor’s explicit selection (via language selector, if enabled)
3. Default Language — this setting
4. Embed config locale — the locale value in the embed code
5. Thai — fallback when nothing else is set

Select “None — follow embed config” to skip this setting and rely on the embed code’s locale value instead.

Note

Default Language only affects the widget UI language. AI response language is controlled separately in AI Settings.

---

Dark Mode & CSS Variables

v1.6.8

The widget supports a built-in dark mode toggle that visitors can activate from the chat header. The entire widget UI is themed using CSS custom properties, ensuring consistent appearance in both modes.

Key CSS Variables

Variable	Description
--cw-primary	Primary brand color (from your theme color setting)
--cw-primary-rgb	RGB components of the primary color, used for transparency effects
--cw-bg	Widget background color
--cw-bg-secondary	Secondary background (input fields, form elements)
--cw-surface	Surface color for cards, tooltips, citation snippets
--cw-text	Primary text color
--cw-text-secondary	Secondary/muted text color
--cw-border	Border color for separators and input outlines

When dark mode is toggled, the widget applies cw-dark or cw-light class to the root container, and all CSS variables update automatically. The gradient header, message bubbles, contact form, and citation chips all respect the current mode.

Note

Dark mode is a visitor-side toggle — it does not persist across sessions. The widget defaults to light mode unless the visitor activates dark mode during their chat session.

---

Preview

After making changes, use the Live Preview panel on the right side of the settings page to see exactly how the widget will appear on your site — before saving.

---

Tips

Tip

• Test your widget on both desktop and mobile to ensure it does not block important page content.
• Use a high-contrast theme color to keep the widget accessible for all users.
• Keep the welcome message short — one or two sentences is ideal. Customers want to ask their question, not read a paragraph.