> 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 choose "Configure Settings" under the Website section 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 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.
* **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`
* **Launcher Border Radius**: Make the square launcher more rounded if desired. Only available when shape is set to Square.
* **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)
***
### 🪟 5. **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 %}
***
### 🧩 6. **Widget Features**
Enable or disable advanced interaction features and conversation management.
* **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).
***
### 💬 7. **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.
***
### ✨ 8. **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.
* **Background Color**: Set the background color of the suggested question buttons.\
Default: `#EDF3F8`
* **Text Color**: Set the text color for the suggested questions.\
Default: `#293037`
* **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.
* **Border Radius**: Control how rounded the suggested question buttons are in pixels.\
Default: `32`
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), 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.