> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/features/chat-widget/customization.md).
# Customization
Alhena provides multiple customization options for its chat widget to ensure it seamlessly integrates with the aesthetic of your website. This guide explores the available customization features.
To begin, access the settings by going to the Alhena dashboard. From there, select "Integrations," and click "Configure" on the Website card to view the chat widget's settings. This allows you to adjust settings and immediately see the effects of your changes.
## 🎨 Widget Customization Options
Alhena AI offers extensive customization options to tailor the website chat widget to your brand and user experience needs. Below is a breakdown of all configurable sections available via the website chat settings in **Integrations > Website**.
***
### 🖼️ 1. **Widget Welcome Text**
Customize the first impression users have when they open the widget.
* **Welcome Screen Icon**: The icon on the welcome screen. On by default and uses the AI Agent Icon unless you upload another. Click reset to revert, or turn the toggle off to hide it.
* **Welcome Screen Title**: Headline text shown at the top.\
Example: `Welcome to Alhena AI ✨`
* **Welcome Screen Subtitle**: Subheading to set context.\
Example: `We delight our customer's customers`
* **Welcome Message**: Default message shown in the chat input area.\
Example: `What can I answer for you?`
* **Add Multiple Welcome Messages**: Click "+ Add welcome message" to add a secondary message.
* **Privacy Consent Button**: Toggle if you want to display a GDPR-style consent before starting the chat.
***
### 🎨 2. **Widget Style**
Visually customize the chat widget itself.
* **AI Agent Icon**: Upload a custom icon for the chat bot.
* **Header Icon**: Optionally upload a different icon for the chat header. Useful when your AI Agent Icon doesn't stand out against the header color (for example, a dark logo on a dark header). If you don't upload one, the header uses the AI Agent Icon. Click the reset button to go back to it.
* **Widget Width**: Width in pixels (e.g., `400`).
* **Widget Border Radius**: Corner rounding for a modern look (e.g., `12`).
* **Header & Button Color**: Customize header and button color using hex codes (e.g., `#0866ff`).
* **Customer Message Color**: Set the text bubble color for user messages.
* **Font Family**: Choose typography (e.g., `Nunito, sans-serif`).
* **Message Font Size**: Font size in pixels (e.g., `15`).
* **Message Line Height**: Vertical spacing between lines in percentages (e.g., `125`).
* **Z-index**: Controls overlay priority. Default `200000` ensures it's above most elements.
***
### 🧿 3. **Widget Launcher**
Control how the widget launcher button appears on the page.
* **Launcher Icon**: Upload your brand logo or avatar. Click the reset button to revert to the default icon.
* **Launcher Icon Padding**: Padding around the icon in pixels.
* **Launcher Text**: Optional label beside the icon (e.g., `Chat with an expert`).
* **Mobile Launcher Text**: Optional separate label for mobile devices.
* **Launcher Background Color**: Customize background (e.g., `#0866ff`).
* **Launcher Text Color**: Typically white (`#ffffff`) for contrast.
* **Desktop Launcher Size** (pixels): Default 66px (min: 44px).
* **Mobile Launcher Size** (optional): Defaults to same as desktop (min: 44px).
* **Launcher Shape**: Choose between:
* `Circle`
* `Square`
* `Speech bubble`: a rounded bubble with one sharp corner pointing toward the corner of the screen where the launcher sits.
* **Launcher Border Radius**: Make the square launcher more rounded if desired. Only available when shape is set to Square.
* **Launcher Border Color** (optional): Adds an outline around the launcher.
* **Launcher Border Width** (pixels): Thickness of the outline. Available once a border color is set.
* **Launcher Animation**: Choose between:
* `None` (default)
* `Typing dots, then text`: the launcher repeatedly shows typing dots, then expands to show your **Launcher Text** before shrinking back to the icon. The animation pauses while the customer has unread messages.
* **Max Animation Loops** (optional): How many times the animation plays before it stops on the icon. Leave blank to keep it playing. Only shown when the animation is on.
* **Z-index**: Controls the launcher's overlay stacking priority.
***
### 📍 4. **Widget Position**
Control where the widget appears on the page.
* **Widget Position**: Choose between `Top Left`, `Top Right`, `Bottom Left`, or `Bottom Right`.
* **Top/Bottom Spacing** (pixels): Set vertical distance from the top or bottom edge (label follows your position choice).
* **Left/Right Spacing** (pixels): Set horizontal distance from the left or right edge (based on your position choice).
* **Use Same Settings for Mobile**: Toggle to reuse the desktop position settings on mobile devices. When unchecked, additional mobile-specific spacing controls appear:
* **Mobile Top/Bottom Spacing** (pixels)
* **Mobile Left/Right Spacing** (pixels)
* **Avoid Overlapping Element (CSS selector)**: The CSS selector of a banner near the widget, such as a cookie notice (e.g. `.promo-banner`). While it's visible, the widget moves up to stay above it. `Bottom Left` and `Bottom Right` positions only.
***
### ⌨️ 5. **Chat Input Field**
Style the message box where customers type, and the send button next to it.
* **Placeholder Text**: Hint text shown in the empty message box (default: `Send a message...`).
* **Input Field Background Color**, **Input Field Text Color** and **Placeholder Text Color**: Colors of the message box and its text.
* **Focus Border Color**: Border color while the customer is typing. Leave empty to keep the border unchanged.
* **Input Field Border Color** and **Input Field Border Radius**: Outline color and corner rounding (e.g., `24px`).
* **Input Height** (pixels): Fixes the message box at this height on a single line, instead of letting it grow as the customer types. Accepts `24` to `120`. Leave blank to keep the growing message box.
* **Input Padding**: Space inside the message box, written like CSS padding (e.g., `14px 18px`).
* **Input Row Margin**: Space around the message box row, written like CSS margin. The first value is the gap above it (e.g., `12px 20px 0 20px`).
* **Send Button Placement**: Choose between:
* `Inside the input`: a round button inside the message box (default).
* `Attached to the input edge`: a square button joined to the right edge of the message box. When **Input Height** is set, the button is as wide as the box is tall.
* **Send Button Icon**: Choose `Arrow` (default), `Sparkle` or `Line arrow`. With `Line arrow` you can also set **Arrow Thickness** (`0.5` to `4`, default `1.6`).
* **Send Button Size** (pixels): Width and height of the send button, or the icon size when the button is attached to the input edge. Accepts `16` to `48` (default `24`).
* **Send Button Icon Color** and **Send Button Background**: Colors of the send button. The background can be a gradient.
* **Send Button Hover Background**: Background shown when a customer hovers over the send button. Leave empty for no hover change.
* **Send Button Icon Color When Empty** and **Send Button Background When Empty**: Colors of the send button while the message box is empty. If you leave both unset, the button is dimmed to 50% instead.
{% hint style="info" %}
Customers can also speak their message instead of typing it. This is controlled by **Let customers speak their message** under **Widget Features**, which is on by default. See [Voice Dictation](/docs/features/chat-widget/voice-dictation.md).
{% endhint %}
***
### 🪟 6. **Expanded View (Centered & Docked)**
The chat widget has two sizes: a **compact** bubble and a larger **expanded** view that gives customers more room to read answers, browse product recommendations, and scroll longer conversations. These settings control whether the widget opens expanded and how that expanded view looks.
* **Open Widget Expanded by Default**: When on, the widget opens directly in its expanded view instead of the compact bubble. Useful when chat is central to the page experience.
* **Show Expand/Collapse Button**: Adds a button in the widget header so visitors can switch between the compact and expanded views themselves.
* **Expanded View Style**: Choose how the expanded widget is displayed. This option appears once either setting above is enabled.
* **Centered**: Opens as a modal in the middle of the screen, with the page dimmed behind it. This is the default.
* **Docked (full-height side panel)**: Opens as a full-height panel pinned flush to the side of the screen, with the rest of the page dimmed behind it. The panel docks to the same side as your **Widget Position** — the right by default, or the left if the widget is positioned on the left.
Docked: a full-height side panel pinned to the edge of the screen.
Centered: a modal in the middle of the screen with the page dimmed behind it.
{% hint style="info" %}
On mobile, the expanded view always fills the screen regardless of the style you pick. Developers can also set and switch the expanded view in code — see [`expandedViewMode`](/docs/developer-reference/website-sdk/javascript-api.md#configuration-options-reference) and [`setExpandedViewMode()`](/docs/developer-reference/website-sdk/javascript-api.md#setexpandedviewmode-mode).
{% endhint %}
***
### 🧩 7. **Widget Features**
Enable or disable advanced interaction features and conversation management.
* **Let Customers Speak Their Message**: Adds a mic button to the chat box, Product FAQ, embedded agents and AI search, so customers can speak instead of typing. See [Voice Dictation](/docs/features/chat-widget/voice-dictation.md).
* **Let Customers Attach Files**: Toggle whether users can upload documents during chat.
* **Let Customers Request Full Chat Transcript**: Allow users to request the full chat transcript via email.
* **Play Sound on New Message**: Plays a notification sound when a new message arrives while the chat widget is closed or the visitor is on a different browser tab. No sound plays while the visitor is actively viewing the chat. Enabled by default.
* **Auto-Close Inactive Conversations**: Toggle to enable or disable automatic closing of inactive conversations. Enabled by default. When enabled, the following options appear:
* **Close After Inactivity (minutes)**: Set the number of minutes of inactivity before a conversation is automatically closed. Accepts a value between `5` and `120` minutes (default: `30`).
* **Auto-Close Message (before escalation)**: The message sent to the customer when a conversation is closed before it has been escalated to a human agent. This message is automatically translated to match the customer's language.\
Default: `It seems this conversation has been inactive for a while, so I'll go ahead and close it. If you need further assistance, feel free to reach out again anytime!`
* **Auto-Close Message (after escalation)**: The message sent to the customer when a conversation is closed after it has been escalated to a human agent. This message is automatically translated to match the customer's language.\
Default: `This conversation will now close due to inactivity. We've received your query and will follow up with you via email shortly.`
#### Expanded View
By default the widget opens as a compact window in the corner of the page. You can let it open larger, or give visitors a button to expand it themselves.
* **Open widget expanded by default**: When on, the chat widget opens already in its expanded view instead of the compact window.
* **Show expand/collapse button**: Adds a button in the widget header so visitors can switch between the compact and expanded views.
* **Expanded view style**: Choose how the expanded view is displayed. This option appears when either setting above is enabled.
* **Centered**: Opens a larger chat window as a modal in the middle of the screen.
* **Docked (full-height side panel)**: Opens a full-height panel pinned to the widget's side of the page (the same side as your **Widget Position** setting).
***
### 💬 8. **Nudge Settings**
Configure how nudges are displayed in the widget. A nudge is a proactive message that appears to engage visitors before they open the chat.
* **Nudge Header Display**: Toggle whether the nudge displays a header with the bot icon and name.
For full nudge configuration (triggers, messages, targeting), go to **Settings > Integrations > AI Nudges**. See the [AI Nudges](/docs/features/chat-widget/nudges.md) documentation for more details.
***
### ✨ 9. **Suggested Questions Settings**
Customize the appearance of AI-generated suggested questions that appear during conversations. These are follow-up questions the AI suggests to help guide the conversation.
* **Suggest catalog terms as customers type**: Shows completions from your product catalog while a customer types. Off by default. See [Suggested Questions](/docs/features/chat-widget/suggested-questions.md). When on:
* **Keep suggesting after the first word**: Off by default, so only the first word gets completions.
* **Match common synonyms**: Matches synonyms, like *couch* for *Sofas*. On by default.
* **AI Icon**: Upload a custom icon displayed alongside the suggested questions, or use the default icon. Click the reset button to revert to the default.
* **Text Color**: Set the text color for the suggested questions.\
Default: `#293037`
* **Font Weight**: Choose `Default` or a weight from `100` to `900`.
* **Background**: Button background. Can be a gradient.\
Default: `#EDF3F8`
* **Hover Background**: Background on hover. Can be a gradient; leave empty for none.
* **Border Color**: Button outline. Can be a gradient.
* **Border Width**: Outline thickness in pixels.\
Default: `1`
* **Border Radius**: Control how rounded the suggested question buttons are in pixels.\
Default: `32`
* **Layout**: `Carousel` (default) shows every question in a sideways-scrolling row; `Stacked` lists up to 4.
* **Use the same layout on mobile**: On by default. Uncheck to pick a separate **Mobile layout**.
A live preview is shown on the right side of the settings panel so you can see your styling changes in real time.
To configure the Suggested Questions agent behavior (enable/disable), click **Configure agent settings** at the bottom of the section, or navigate to **AI Settings > Agents > Suggested Questions**. See the [Suggested Questions](/docs/features/chat-widget/suggested-questions.md) page for a full overview of the feature, or [Built-in Agents](/docs/ai-configuration/agents/built-in-agents.md) for agent details.
***
### 🔘 10. **Quiz Options**
Style the multiple-choice buttons of [Quiz Options](/docs/features/chat-widget/quiz-options.md).
* **Text Color**: Defaults to your agent message text color.
* **Font Weight**: `100` to `900`.\
Default: `500`
* **Background**: Defaults to your agent message background color.
* **Hover Background**: Background on hover. Can be a gradient; leave empty for none.
* **Border Color**: Defaults to the text color.
* **Border Width**: Outline thickness in pixels.\
Default: `1`
* **Border Radius**: Corner rounding in pixels. Leave blank for the default shape.
***
### 👁️ 11. **Page Visibility**
Choose which pages of your website show the chat widget.
* **Show the chat widget on**: Choose between:
* `All pages` (default)
* `Only on matching pages`: the widget shows only on pages that match a condition below.
* `All pages except matching pages`: the widget is hidden on pages that match a condition below.
* **Matching pages**: Click **Add condition** to add a page. For each condition, pick a **Field** (`Page URL` or `Page Title`), an **Operator** (`Contains at least one of`, `Doesn't contain`, `Is` or `Is not`), and one or more **Values**, one per line (e.g. `/checkout`).
* **Ignore URL parameters (everything after ?)**: For `Page URL` conditions, check this to match the page whatever comes after the `?` in its address.
A page matches when all of its conditions match. With `Only on matching pages` and no conditions, the widget shows on no pages.
{% hint style="info" %}
Product FAQs and embeddable agents still show on pages where the chat widget is hidden.
{% endhint %}
