> ## Documentation Index
> Fetch the complete documentation index at: https://help.clientx.in/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure the ClientX Widget Appearance and Behavior
> Customize the ClientX widget's colors, agent name, welcome message, suggested questions, and proactive SmartBar using the dashboard or embed config.
Configuration is set in your dashboard under **Settings → Widget** and applied automatically to every visitor session — you never need to change the script tag on your website after the initial install. When you save a change in the dashboard, the widget fetches fresh config on the next session start with no redeployment required.
## Dashboard configuration
These are the main fields you configure in the **Settings → Widget** UI. Each field maps directly to a property in the `ClientXConfig` interface that the widget receives at session start.
| Field | Config key | Description |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
| Agent Name | `agentName` | First name of your AI agent (e.g. `"Sam"`). Shown in the header as **Sam from Acme**. |
| Company Name | `workspaceName` | Your company name (e.g. `"Acme"`). Shown alongside the agent name. |
| Agent Avatar | `agentAvatar` | URL to a square image for the agent's avatar. Displayed in the header and on each assistant message bubble. |
| Primary Color | `primaryColor` | Hex color used for the send button, CTA button, and accent elements. Defaults to `#7F77DD`. |
| Welcome Message | `welcomeMessage` | The subtitle text shown below the greeting on the home screen (e.g. `"Ask me anything. I'll answer fast."`). |
| Chat Placeholder | `chatPlaceholder` | Placeholder text in the input field and the launcher bar. Defaults to `"Ask [agentName] anything"`. |
| Widget Title | `widgetTitle` | Fallback title shown in the header if neither `agentName` nor `workspaceName` is set. |
If you set both `agentName` and `workspaceName`, the header reads **"{agentName} from {workspaceName}"** — this humanises the agent and reinforces your brand at the same time.
***
## Suggested questions
Suggested questions appear as clickable chips on the widget home screen and in the launcher bar's rotating placeholder. You have two modes:
In `ai` mode the widget automatically generates contextual questions by scraping the visible text on the current page (title, meta description, headings, and body paragraphs) and sending it to the ClientX server. Questions update automatically on every SPA navigation so visitors always see relevant chips no matter which page they're on.
This is the default — you don't need to configure anything to enable it.
```json theme={null}
{
"suggestedQuestionsMode": "ai"
}
```
The widget also falls back to AI-generated questions in the launcher bar's rotating placeholder while it waits for the server response, cycling through built-in defaults first.
In `manual` mode you supply a fixed list of questions. These are shown on every page and never change. Use this when your site has a single focus or when you want to guarantee specific conversion questions always appear.
```json theme={null}
{
"suggestedQuestions": [
"How does pricing work?",
"Can I book a demo?",
"What integrations do you support?"
],
"suggestedQuestionsMode": "manual"
}
```
The widget shows up to **four chips** on the home screen and up to **three chips** in the collapsed launcher.
***
## SmartBar
The SmartBar is a proactive bubble that appears after a configurable delay to engage visitors before they leave. On desktop it appears as a floating "Dynamic Island" pill above the launcher. On mobile it injects the message into the launcher placeholder instead to avoid a double-pill layout.
```json theme={null}
{
"smartBar": {
"enabled": true,
"mode": "ai",
"delayMs": 3000,
"dismissible": true
}
}
```
When a visitor clicks the SmartBar, the widget opens and sends the proactive message as the first turn of the conversation. If the visitor dismisses it, the dismissed state is stored in `sessionStorage` and the bubble does not re-appear for the rest of that browser session.
### SmartBar parameters
Set to `true` to activate the SmartBar. When `false` (the default) no proactive bubble is shown.
Controls how the proactive message is generated.
* `"ai"` — The server generates a personalized opener based on the current page URL, using your knowledge base for context. Falls back to `message` if the request fails.
* `"manual"` — Uses the static `message` string you provide.
The static message shown when `mode` is `"manual"`, or used as a fallback when `mode` is `"ai"` and the server request fails. If this is empty and the server request also fails, the widget uses `"Have a question? I can help."` as a last resort.
Optional label appended to a generic fallback message (e.g. `"Book a Demo - ask me anything"`). Only used when `message` is empty and the AI fetch fails.
Milliseconds to wait after page load before showing the SmartBar. Set higher values (e.g. `8000`) on pages where you want visitors to read before being interrupted.
When `true`, a dismiss (×) button appears on the expanded bubble. When `false`, the visitor can only interact by clicking the bubble — they cannot close it without opening the widget.
***
## AI Section
The AI Section is an embedded ask-anything bar you can place anywhere on your page by adding a `data-clientx-section` attribute to a container element. It renders inside a Shadow DOM so your page CSS does not affect it.
```html theme={null}
```
Configure the section's appearance with the `aiSection` config object:
```json theme={null}
{
"aiSection": {
"enabled": true,
"headline": "Got questions about our product?",
"placeholder": "Ask anything — I'll answer in seconds",
"suggestions": [
"How does the free trial work?",
"What does onboarding look like?",
"Can I import my existing data?"
]
}
}
```
### AI Section parameters
Set to `true` to activate the AI Section on any element with `data-clientx-section`.
Large bold heading rendered above the input bar (e.g. `"Got questions about our product?"`).
Placeholder text inside the input field. Defaults to `"Ask me anything…"` if not set.
Array of pill-style suggestion chips rendered below the input bar. Up to four are shown. Clicking a chip opens the main widget panel and sends the question automatically.
***
Changes saved in the dashboard take effect immediately on the next visitor session — no redeployment or script tag update needed. The widget always fetches the latest configuration at session start.