# Customize how the widget looks and behaves

> Pick where the chat appears, match your brand, and set the welcome, chat bubble, replies and features.

Every widget setting lives on the deployment, and the widget picks up changes the next time it loads. Settings are split across two tabs: **Settings** for where the widget appears, its tabs, limits and who may embed it, and **Chat widget** for how the chat looks and behaves. Select **Save changes**, then **Preview** at the top to try them.

## Placement

Choose it under **Settings** → **Placement**.

| Placement | What visitors see | Good for |
| --- | --- | --- |
| Chat bubble | A bubble in the corner that opens the chat | Most websites |
| Inline on the page | The chat as a block inside your page | Help pages and in-app assistants |
| Full screen | The chat filling the element you place it in | A dedicated chat page |
| Pop-up window | A window over your page, opened by your own button | An "Ask AI" button |
| Side panel | A full-height panel docked to the left or right edge | Chatting while the page stays usable |

For a pop-up window, or a bubble you hide, your page opens the chat. See [Open the chat from your own buttons and links](https://docs.help.ai/customize-and-extend-the-widget/open-the-chat-from-your-page).

The rest of this article covers the **Chat widget** tab, from top to bottom.

## Welcome

- **Welcome messages (optional):** one per line, sent by the agent when the chat opens. Up to 20, each up to 1,000 characters.
- **Suggested replies (optional):** one per line, shown as buttons under the welcome messages, such as "How do I get started?". Up to 50.

## Theme

Under **Theme**, choose **Match system** (the default), **Light** or **Dark**, or **Custom** to set your own:

| Field | What it sets |
| --- | --- |
| **Accent colour** | The bubble, the send button and links, such as `#6366f1` |
| **Text on accent** | Text and icons on top of the accent colour |
| **Corner radius** | In pixels, such as `12px`. `0` gives square corners |
| **Font** | Such as `Inter, sans-serif` |
| **Content width** | How wide messages get on big screens, such as `768px`. Use `100%` to fill |

<Tip>
Current browsers pick black or white text on the accent for you, and may adjust a very light or very dark accent so it stays readable. **Text on accent** is used by older browsers.
</Tip>

## Chat bubble

With the **Chat bubble** placement, the **Chat bubble** section sets:

- **Style:** **Round button** (the default), **Pill with label**, **Bar with label** or **Minimal**
- **Size:** **Small**, **Medium** (the default) or **Large**
- **Label:** the text on the pill, bar and minimal styles, such as "Ask AI"
- **Icon:** `chat`, `spark`, `message`, `help` or `wand`
- **Hide the bubble:** turn it on if your page opens the chat with its own button

Under **Callout bubble**, an **Invite message** shows a short line next to the bubble, such as "Hi! Need a hand?":

| Setting | Default | What it does |
| --- | --- | --- |
| **Shape** | Pill | **Pill**, **Speech bubble** or **Callout** |
| **Position** | Automatic | **Automatic**, **Beside the button** or **Above the button** |
| **Delay (ms)** | 1200 | How long to wait before showing it, up to 60,000 |
| **Auto-dismiss (ms)** | 0 | Hides it after this long. `0` keeps it until the visitor closes it |
| **Animate** | On | A small nudge to draw the eye. Visitors who prefer reduced motion don't see it |
| **Re-show on every visit** | On | When off, a closed invite stays hidden until you change its text |

## Size and position

| Setting | What it does |
| --- | --- |
| **Position** | Bottom right (the default), bottom left, top right or top left. For **Chat bubble** and **Side panel** |
| **Width**, **Height** | Such as `420px` or `90vw` |
| **Initial size** | How big the chat is when it first opens |
| **Wide screen from (px)** | With **Initial size** set to **Automatic (large on wide screens)**, screens at least this wide open the chat large. 900 if empty |
| **Panel margin** | **Side panel** only: the space between the panel and the screen edges |
| **Expanded width**, **Expanded height** | The size when the visitor expands the chat |
| **Visitors can resize** | Visitors drag the chat bubble's corner, or the side panel's inner edge (width only), and the chat keeps that size next time. Minimums are 320px wide and 400px tall unless you set your own; maximums are optional. Hidden on phones, where the chat fills the screen. Off by default |

## Header buttons

Choose the buttons in the chat header: **Clear chat**, **Expand**, **Full screen**, **Open in new window**, **Sound**, **Conversation history**, **Language**, **Light or dark**, **Text size** and **Close**. **Conversation history** and **Close** get their own buttons; the rest share the ⋯ menu.

- Until you change them, the buttons follow the placement: all ten for **Chat bubble**, fewer for the others. Buttons a placement can't use stay hidden, such as **Expand** anywhere but the chat bubble.
- **Open in new window** shows only when **Open-in-new-window address** is set under **Behavior**.
- **Language** shows only when the deployment offers two or more languages.

## Message box

| Setting | What it does |
| --- | --- |
| **Button shape** | **Round**, **Square** or **Pill** |
| **Button icon** | **Arrow up**, **Paper plane**, **Send** or **Chevron** |
| **Button fill** | **Filled**, **Outline** or **Icon only** |
| **File size in bytes** | The largest file a visitor can attach. 10 MB (10,485,760) by default, which is also help.ai's limit per file |
| **Files per message** | 10 by default, up to 100 |
| **File types** | Such as `image/*, application/pdf` |

## Footer

- **Note (optional):** small text under the message box, such as "AI can make mistakes. Verify important answers." Leave it empty to hide it.
- **Powered-by text**, **Powered-by link** and **Powered-by logo (optional)** set the "Powered by" line. Upload the logo, or select **Use a link** for one hosted elsewhere.

## Behavior

This section isn't shown for **Full screen** or a hosted page, where the chat is always open.

| Setting | Default | What it does |
| --- | --- | --- |
| **Start closed** | On | On a first visit, shows only the bubble instead of opening the chat. For **Chat bubble**, **Pop-up window** and **Side panel** |
| **Replies appear** | Word by word | **Word by word** as they're written, or **All at once** when finished |
| **Show thinking** | Off | Lets visitors expand how the agent worked out a reply |
| **Show actions** | Off | Shows when the agent looks something up or takes an action. Questions and approval requests always show |
| **Show sources** | Off | Lists the articles and pages a reply is based on |
| **Reply feedback** | On | Thumbs up and down under each reply |
| **Auto-send suggestions** | Off | Tapping a suggested reply sends it right away instead of filling the message box |
| **Open-in-new-window address** | Empty | The page **Open in new window** opens, such as `https://app.example.com/chat` |

## Features

| Feature | Default | What it does |
| --- | --- | --- |
| **File uploads** | On | Visitors can attach, drop or paste files |
| **Visitor approvals** | On | The agent asks before some actions, and can ask for missing details |
| **Suggested replies** | On | Offers replies to tap after each answer |
| **Talk to a person** | Off | Adds a **Talk to a person** button to the message box. Requests land in **Inbox**. See [Let visitors talk to a person](https://support.help.ai/inbox-and-cases/let-visitors-talk-to-a-person) |
| **Voice input** | In the browser | **In the browser**, **On our servers** or **Off** |
| **Visitor memory** | This agent | What the agent remembers about a returning visitor |
| **Tools in this chat (optional)** | None | Extra tools for this deployment only, from the tools turned on in your workspace. They're added to the agent's own tools |
| **Skills in this chat (optional)** | None | Extra skills for this deployment only. They're added to the agent's own skills |
| **Integrations in this chat (optional)** | None | Extra integrations for this deployment only, added to the agent's own. Visitors only get the ones shared with visitors. See [Give your agent tools and integrations](https://support.help.ai/ai-agents/tools-connected-accounts-and-credentials) |

**Visitor memory** has three options:

- **This conversation only:** each conversation starts fresh.
- **This agent (default):** the agent remembers the same visitor across all of its deployments.
- **All of your agents:** every agent in your workspace remembers the same visitor.

The agent recognizes a returning visitor by their browser.

## Forms, languages, and sounds

- **Forms:** show your forms in the chat at a moment you choose, up to 20. See [Show a form in the chat widget](https://support.help.ai/forms/show-a-form-in-the-chat-widget).
- **Languages:** see [Offer the widget in several languages](https://support.help.ai/deployments-and-the-widget/offer-the-widget-in-several-languages).
- **Sounds and vibration:** **Sound notifications** plays a tone for new replies (on, at a **Volume** of 0.3 out of 1). **Vibration** is on, for phones and tablets that support it. Browsers may still block sound.

<Tip>
To follow your own site's light and dark mode, or restyle the widget with CSS, see [Match your site's theme and style the widget](https://docs.help.ai/customize-and-extend-the-widget/match-your-theme-and-style-the-widget).
</Tip>