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.

For options and settings beyond these tabs, see Custom Settings.

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:

Brand Matching

Set colors, fonts, and avatars so the widget feels native to your site

Proactive Engagement

Configure automatic pop-outs, chat prompts, and notifications to initiate conversations with visitors

Flexible Layout

Choose between a floating bubble or a full-page embedded chat, and adjust dimensions and corner radius

Advanced Control

Add persistent menu buttons, control file uploads, and inject custom JSON settings for developer-level overrides

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.

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.

Setting	Description
Mode	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.
Widget Radius	Controls the corner curvature of the chat window (0 px for sharp corners, up to 32 px for rounded).
Widget Width / Height	Sets the dimensions of the expanded chat window in pixels. Only available in Bubble mode.
Header Style	Choose between a left or center header bar at the top of the chat window.
Agent Header	The text displayed in the chat window header. This is what visitors see, so pick something approachable.
Font Family	The typeface used inside the widget. Match it to your site's typography for a seamless look.
Link Behavior	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.

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.

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.

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.

Notification text

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.

Image

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.

Image Links To

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

Enable Buttons

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.

Delete

Delete the notification immediately from the chain using the delete icon .

Lock typing until dismissed: The startupNotificationsRequireDismissal custom setting keeps the input box locked until the visitor dismisses a start up notification (off by default).

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.

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.

Notification delay

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 , buttons for increments of 10.

Play sound

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.

Advanced settings

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.

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. Each field accepts a hex color value or use the color picker to select one visually.

Setting	What It Controls
Main Color	The widget header and primary accent
Main Font Color	Text in the header and primary UI elements
Hyperlink Color	Clickable links inside messages
Agent Bubble Color	Background of the agent's message bubbles
Agent Bubble Text Color	Text inside the agent's message bubbles
User Bubble Color	Background of the user's message bubbles
User Bubble Text Color	Text inside the user's message bubbles

Test color combinations for accessibility. Ensure sufficient contrast between bubble background and text colors so messages remain readable.

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):

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.

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

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.

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.

1. After clicking the button, the visitor sees a set of deployment buttons. You can create up to 4 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.

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

Additional toggles:

Hide Upload Button

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

Hide Emoji Button

Removes the emoji picker from the input bar.

Hide Typing Indicator

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

Enable Menu Buttons

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

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.

Speech Credentials

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.

TTS Voice

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

For deployments that need to route token requests through their own backend, see azureSpeechTokenURL under Custom Settings and reach out to the support team to wire it up.

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.

For the full reference of every setting you can pass to the widget, see Custom Settings.

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.

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

You can now style the Webchat widget to match your brand and control how it greets and engages visitors.