> For the complete documentation index, see [llms.txt](https://docs.helvia.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helvia.ai/deploy/webchat/layout-settings.md).

# Layout Settings

Customize how the Webchat widget looks and behaves

Layout Settings gives you full control over how the Webchat widget looks and behaves, from brand colors and avatars to notifications, actions, and voice. Everything is configured visually, tab by tab, with no code required. You'll find it while editing a Webchat deployment in **Designer > Deployments** under **Layout Settings**.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FJ24BS5EgfIJjMotTEPYb%2Flayout%20settings.png?alt=media&amp;token=04f0dcdb-0c98-48ef-86c4-f9c3b0a811e0" alt="" width="375"><figcaption></figcaption></figure></div>

For options and settings beyond these tabs, see [Custom Settings](/deploy/webchat/custom-settings.md).

### What Are Layout Settings

Layout Settings is a group of tabs in a Webchat deployment, each controlling one aspect of the widget. You set colors in one tab, notifications in another, and so on. At a glance, the tabs cover:

<table data-card-size="large" data-column-title-hidden data-view="cards"><thead><tr><th>Feature</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-palette">:palette:</i></h4><h4>Brand Matching</h4></td><td>Set colors, fonts, and avatars so the widget feels native to your site</td></tr><tr><td><h4><i class="fa-comments">:comments:</i></h4><h4>Proactive Engagement</h4></td><td>Configure automatic pop-outs, chat prompts, and notifications to initiate conversations with visitors</td></tr><tr><td><h4><i class="fa-table-layout">:table-layout:</i></h4><h4>Flexible Layout</h4></td><td>Choose between a floating bubble or a full-page embedded chat, and adjust dimensions and corner radius</td></tr><tr><td><h4><i class="fa-gears">:gears:</i></h4><h4>Advanced Control</h4></td><td>Add persistent menu buttons, control file uploads, and inject custom JSON settings for developer-level overrides</td></tr></tbody></table>

Click **View Example** in any Layout Settings tab to open an annotated diagram of the widget in Bubble mode. The diagram labels every customizable area such as header, avatars, bubble colors and more.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2Fr56QxHKJuQ6EuEZsX9w8%2Fwebchat%20example.jpg?alt=media&amp;token=66897f0e-e1a5-40ef-8b72-ae441b59b67c" alt="" width="375"><figcaption></figcaption></figure></div>

### General

These settings define the widget's structure and how it fits into your site, starting with the choice between a floating Bubble or a full-page Embedded layout.

<table data-search="true"><thead><tr><th width="224.5">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Mode</strong></td><td>Bubble renders the widget as a floating button in the bottom-right corner that expands on click. Embedded renders the widget inline as a full-page chat, useful for dedicated support pages.</td></tr><tr><td><strong>Widget Radius</strong></td><td>Controls the corner curvature of the chat window (0 px for sharp corners, up to 32 px for rounded).</td></tr><tr><td><strong>Widget Width / Height</strong></td><td>Sets the dimensions of the expanded chat window in pixels. Only available in Bubble mode.</td></tr><tr><td><strong>Header Style</strong></td><td>Choose between a left or center header bar at the top of the chat window.</td></tr><tr><td><strong>Agent Header</strong></td><td>The text displayed in the chat window header. This is what visitors see, so pick something approachable.</td></tr><tr><td><strong>Font Family</strong></td><td>The typeface used inside the widget. Match it to your site's typography for a seamless look.</td></tr><tr><td><strong>Link Behavior</strong></td><td>Control whether links and link buttons sent by the agent open in the same tab or a new tab. Opening in a new tab keeps the conversation visible.</td></tr></tbody></table>

{% hint style="info" %}
You can select alternative fonts in case the primary one is not supported by the system of the end-user. If the host website loads custom fonts, the widget can use those too.

![](https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FgVP2CXcLkuZzsbXjoWC6%2FScreenshot%202026-03-10%20at%202.06.52%E2%80%AFPM.png?alt=media\&token=c3144a7e-1894-400f-b9f1-ae053b94e198)
{% endhint %}

### Start Up Notifications

Start up notifications appear when the widget first loads, useful for greeting visitors, showcasing promotional banners, or nudging users toward a specific workflow. They sit in front of the conversation messages and stay visible until the visitor dismisses them or selects one of the attached buttons.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2F4FnGweHzjGFgf5Hrg5qS%2FScreenshot%202026-03-10%20at%202.52.17%E2%80%AFPM.png?alt=media&amp;token=930d288d-d38f-4fc2-aad6-122a17c127aa" alt="" width="179"><figcaption></figcaption></figure></div>

Select **Add Notification** to configure a notification. A notification is valid with a text message or an image, or both, and it can display up to three buttons. You can chain multiple notifications together by adding a new one again.

<details>

<summary><i class="fa-message-text">:message-text:</i>  <strong>Notification text</strong> </summary>

The message shown to the user. It is optional as long as the notification includes an image. Keep it short so you don't overwhelm the visitor.

</details>

<details>

<summary><i class="fa-image">:image:</i> <strong>Image</strong></summary>

Attach an image on its own or alongside the text, from an upload, the Media Library, or a URL. It renders at the notification's full width and is never cropped, so any aspect ratio works, wide or square. The tooltip lists the recommended dimensions, file-size limit, and supported formats.

</details>

<details>

<summary><i class="fa-link">:link:</i> <strong>Image Links To</strong></summary>

Optional URL opened in a new tab when the visitor clicks the image. The field stays disabled until an image is added.

</details>

<details>

<summary><i class="fa-square-check">:square-check:</i>  <strong>Enable Buttons</strong></summary>

Attach one, two or three buttons to turn a passive notification into an interactive entry point. Each button has a **Button Name** (the label visitors see) and a **Flow** (the workflow triggered on click). For example, a "Talk to Sales" button can route users directly into a sales qualification workflow.

</details>

<details>

<summary><i class="fa-trash-can">:trash-can:</i>  <strong>Delete</strong></summary>

Delete the notification immediately from the chain using the delete icon <i class="fa-trash-can">:trash-can:</i>.

</details>

{% hint style="info" %}
**Lock typing until dismissed:** The `startupNotificationsRequireDismissal` [custom setting](/deploy/webchat/custom-settings.md#core-settings-1) keeps the input box locked until the visitor dismisses a start up notification (off by default).
{% endhint %}

### Idle Notifications

Idle notifications re-engage visitors who opened the widget but stopped interacting. They share the same core settings as start up notifications (text, optional buttons, adding and removing) but offer additional controls: a delay before the notification appears, a sound toggle to grab attention, and the ability to automatically trigger a workflow when the idle threshold is reached.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2Ff3diRBmCYNwd2L65rNoR%2FScreenshot%202026-03-10%20at%204.23.40%E2%80%AFPM.png?alt=media&amp;token=5a44d154-5bd2-4796-9bde-26b9ef0f7e12" alt="" width="183"><figcaption></figcaption></figure></div>

Idle notifications disappear automatically once the visitor starts typing. Use them to recover abandoned conversations. A message like "Still have questions? I'm here whenever you're ready" can prompt users to resume the chat.

<details>

<summary><i class="fa-timer">:timer:</i>  <strong>Notification delay</strong></summary>

Set how many seconds of inactivity must pass before the notification appears. A shorter delay (e.g., 10 seconds) works for quick support prompts, while a longer delay (e.g., 60 seconds) avoids interrupting users who are still reading. You can type the amount of delay you want or use the <i class="fa-plus">:plus:</i>, <i class="fa-minus">:minus:</i> buttons for increments of 10.&#x20;

</details>

<details>

<summary><i class="fa-volume">:volume:</i>  <strong>Play sound</strong></summary>

Toggle a sound effect that plays when the idle notification appears. This adds an audible cue alongside the visual notification, useful for visitors who have scrolled away or switched tabs.

</details>

<details>

<summary><i class="fa-arrow-progress">:arrow-progress:</i>  <strong>Advanced settings</strong></summary>

Automatically start a workflow when the idle threshold is reached. Instead of just showing a notification, the agent can proactively send a message, ask a question, or begin a guided workflow, turning inactivity into an opportunity to re-engage the visitor. Select the workflow you want to trigger from the dropdown.

</details>

### Avatars

Avatars give the conversation a human feel and reinforce brand identity.

* **Agent Avatar:** Upload an image, select from your Media Library, or provide a URL for the icon that appears next to the agent's messages
* **User Avatar:** Same options for the visitor's icon

Both are optional. If no avatar is set, the widget displays a default icon.

### Colors

Match the widget to your brand palette. Enter a hex value in each field, or use the color picker to select one visually

<table><thead><tr><th width="281">Setting</th><th>What It Controls</th></tr></thead><tbody><tr><td><strong>Main Color</strong></td><td>The widget header and primary accent</td></tr><tr><td><strong>Main Font Color</strong></td><td>Text in the header and primary UI elements</td></tr><tr><td><strong>Hyperlink Color</strong></td><td>Clickable links inside messages</td></tr><tr><td><strong>Agent Bubble Color</strong></td><td>Background of the agent's message bubbles</td></tr><tr><td><strong>Agent Bubble Text Color</strong></td><td>Text inside the agent's message bubbles</td></tr><tr><td><strong>User Bubble Color</strong></td><td>Background of the user's message bubbles</td></tr><tr><td><strong>User Bubble Text Color</strong></td><td>Text inside the user's message bubbles</td></tr></tbody></table>

{% hint style="info" %}
Test color combinations for accessibility. Ensure sufficient contrast between bubble background and text colors so messages remain readable.
{% endhint %}

### Actions

Actions control how the widget behaves before and during a conversation.

**Action Layout** determines how the agent presents interactive elements like buttons:

* **Stacked:** Buttons arranged vertically
* **Carousel:** Buttons displayed in a horizontal scrollable row
* **Flow:** Buttons follow the workflow's native layout

**Bubble Action** controls what happens to the bubble when the page loads (Bubble mode only):

{% tabs %}
{% tab title="No Bubble Action" %}
The widget stays collapsed until the visitor clicks it. Use this for pages where the chat should be available but not intrusive.
{% endtab %}

{% tab title="Automatic Pop-out" %}
The widget opens automatically after a set number of seconds. Configure the Pop-out Time to control the delay. Good for landing pages where you want to proactively engage visitors.

Additional timing options:

* **No advanced time settings:** Default behavior, automatic pop-out after the configured delay
* **Double pop-out time after every view:** On each page refresh double the configured delay
* **Pop-out only once:** The widget opens once; subsequent page loads keep it collapsed
  {% endtab %}

{% tab title="Chat Prompt" %}
Instead of opening the full widget, a small prompt message appears after a set time (e.g., "Need help?"). This is less intrusive than a full pop-out and gives the visitor the choice to engage.

Configure the Pop-out Time and set the Chat Prompt Message with the text shown in the chat prompt.

<div align="left" data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FiGVSQAnlxMGEksyoBxjs%2FScreenshot%202026-03-10%20at%206.11.22%E2%80%AFPM.png?alt=media&amp;token=b3717cbd-dce9-4bdb-b15f-0d3ed90855ef" alt="" width="216"><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Advanced Chat Prompt" %}
A multi-step prompt that appears when the visitor clicks the bubble icon, before the conversation begins. Use this to greet visitors and route them to different deployments.

The interaction has two steps:

1. The visitor clicks the bubble and sees a message with a single button. Configure the text with **Step One Message** and the button label with **Step One Button Label**.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FRnoLhtRJPgFFWCmwtlXB%2FScreenshot%202026-03-13%20at%2011.08.09%E2%80%AFAM.png?alt=media&amp;token=f5d91e7c-e452-4831-9389-846da6a1bb5a" alt="" width="188"><figcaption></figcaption></figure></div>

2. After clicking the button, the visitor sees a set of deployment buttons. You can create up to four buttons. Each button has a configurable **Deployment URL** and **Deployment Icon**, allowing you to route visitors to different channels (e.g., Webchat, Messenger, WhatsApp). For web deployment, the deployment URL should be left empty.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FBJzcaLYRE3pKd4XUuJSx%2FScreenshot%202026-03-13%20at%2011.08.14%E2%80%AFAM.png?alt=media&amp;token=b5ae55bc-e961-4c24-8e65-7f0503066fef" alt="" width="188"><figcaption></figcaption></figure></div>

This is useful when you want a single entry point on your site that branches into multiple support channels or specialized agents.
{% endtab %}
{% endtabs %}

Additional toggles:

<details>

<summary><i class="fa-paperclip-vertical">:paperclip-vertical:</i>  <strong>Hide Upload Button</strong></summary>

Prevents visitors from uploading files. Enable this if your agent does not process attachments.

</details>

<details>

<summary><i class="fa-face-smile">:face-smile:</i>  <strong>Hide Emoji Button</strong></summary>

Removes the emoji picker from the input bar.

</details>

<details>

<summary><i class="fa-comment-dots">:comment-dots:</i>  <strong>Hide Typing Indicator</strong></summary>

Hides the "typing..." animation while the agent processes a response.

</details>

<details>

<summary><i class="fa-table-cells-large">:table-cells-large:</i>  <strong>Enable Menu Buttons</strong></summary>

Adds persistent buttons to the widget that trigger specific workflows, regardless of where the user is in the conversation.

</details>

### Speech

The Speech tab adds spoken conversation to your Webchat deployment, enabling speech-to-text and text-to-speech for visitors.

Toggle **Enable Speech** to turn voice features on. When disabled, the microphone button is hidden from the widget.

<details>

<summary><i class="fa-microphone">:microphone:</i> <strong>Speech Credentials</strong></summary>

Choose which Azure Speech credentials run this deployment:

* **Helvia (global credentials):** Use Helvia.ai's default Azure Speech subscription. No setup required.
* **Custom Integration:** Use your own Azure Speech integration from **Workspace > Integrations**.

</details>

<details>

<summary><i class="fa-volume-high">:volume-high:</i> <strong>TTS Voice</strong></summary>

Set the text-to-speech voice the agent uses (e.g., `en-US-JennyNeural`). Pick a voice that fits your audience and brand.

</details>

{% hint style="info" %}
For deployments that need to route token requests through their own backend, see `azureSpeechTokenURL` under [Custom Settings](/deploy/webchat/custom-settings.md) and reach out to [the support team](/resources/support.md) to wire it up.
{% endhint %}

### Custom

Toggle **Enable Custom Settings** to pass additional configuration as raw JSON. This is an advanced option for developers who need to inject custom attributes or override default behavior beyond what the visual settings offer.&#x20;

For the full reference of every setting you can pass to the widget, see [Custom Settings](/deploy/webchat/custom-settings.md).

{% hint style="warning" %}
If you need multiple custom settings, merge them into a single JSON object. Do not paste separate JSON blocks, or they will fail the validation check. Combine all keys under one root object instead.
{% endhint %}

### Best Practices

* **Match your brand:** Set colors, fonts, and a recognizable avatar so the widget feels native to your site, not bolted on
* **Start with Bubble mode:** A floating widget suits most sites; reserve Embedded mode for dedicated support or help pages
* **Prefer a Chat Prompt over an automatic pop-out:** A subtle prompt respects the visitor's attention more than a widget that opens unprompted
* **Check color contrast:** Ensure bubble backgrounds and text stay readable, so the widget is accessible to all visitors

{% hint style="success" %}
You can now style the Webchat widget to match your brand and control how it greets and engages visitors.
{% endhint %}