> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpalive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize the Agent's appearance and branding

> Match the HelpAlive Agent to your product brand. Colors, layout, welcome message, and content — all configurable from Agent → Appearance.

The **Agent → Appearance** tab is where you make the Agent feel like it belongs in your product — colors, layout, welcome message, and personalization tokens. No code changes, no deploys.

## Where to configure

Open your dashboard and go to **Agent → Appearance**. The tab is split into three sub-sections:

| Sub-tab     | What you control                                                              |
| ----------- | ----------------------------------------------------------------------------- |
| **Colors**  | Primary brand color, color scheme (light / dark / system), header background. |
| **Content** | Welcome message, input placeholder, suggested-question framing.               |
| **Layout**  | Launcher position, side and bottom spacing, custom launcher logos.            |

Every change is staged as a draft. Use the **Test** tab to preview your changes, then publish from any Agent tab when you're ready.

## Configuration options

| Setting               | Description                                                                        | Default               |
| --------------------- | ---------------------------------------------------------------------------------- | --------------------- |
| **Color**             | Primary color used for the launcher button, send button, and message accents.      | `#6366f1`             |
| **Color scheme**      | `light`, `dark`, or `system` (follows the user's OS preference).                   | `system`              |
| **Header background** | Solid color or two-stop gradient.                                                  | Solid                 |
| **Welcome message**   | First message shown when a user opens the widget. Supports personalization tokens. | "Hi! How can I help?" |
| **Placeholder**       | Input hint text.                                                                   | "Ask a question…"     |
| **Position**          | Which corner of the viewport the launcher pins to.                                 | `bottom-right`        |
| **Side spacing**      | Horizontal offset from the viewport edge in pixels.                                | `24`                  |
| **Bottom spacing**    | Vertical offset from the viewport edge in pixels.                                  | `24`                  |
| **Launcher logo**     | Custom SVG/PNG for the launcher button (light + dark variants).                    | HelpAlive icon        |

## Personalization tokens

Welcome messages can use these tokens:

| Token           | Resolves to                                                                            |
| --------------- | -------------------------------------------------------------------------------------- |
| `{displayName}` | The user's display name from your `identify()` call. Falls back to "there" if missing. |
| `{tenantName}`  | The workspace name from `identify()`.                                                  |
| `{plan}`        | The user's plan (e.g. `pro`, `enterprise`).                                            |
| `{role}`        | The user's role.                                                                       |

Example:

```
Hey {displayName}! I'm here to help with anything in your {tenantName} workspace.
```

## Color scheme behavior

| Setting  | Behavior                                                        |
| -------- | --------------------------------------------------------------- |
| `light`  | Always light, regardless of OS or host page.                    |
| `dark`   | Always dark.                                                    |
| `system` | Follows the user's OS preference, switching live as it changes. |

The widget is fully isolated from your page styles, so your CSS won't accidentally change how the Agent looks. You control its appearance entirely from the dashboard.

## Position presets

| Position       | When to use                                                          |
| -------------- | -------------------------------------------------------------------- |
| `bottom-right` | Default; works for most apps.                                        |
| `bottom-left`  | When your product already has its own help/menu in the bottom-right. |
| `top-right`    | Rare; landscape kiosks or single-page tools with bottom navigation.  |
| `top-left`     | Rare.                                                                |

If your product has a fixed bottom bar, increase **Bottom spacing** so the launcher clears it.

## Custom launcher logo

Upload SVG (preferred) or PNG variants for light and dark modes. The widget swaps automatically based on the active color scheme.

| Variant    | When used           |
| ---------- | ------------------- |
| Light logo | Light color scheme. |
| Dark logo  | Dark color scheme.  |

Recommended size: 32×32 pixels. SVGs are preferred because they stay sharp on any screen.

## Localization

The welcome message and placeholder are stored as plain strings — set them to your primary language. Agent answers themselves are generated in the language of the user's question; no manual translation step required.

## Hiding the Agent

There are three ways:

1. **Per-user, runtime** — call `HelpAlive.setConsent({ chat: false })`.
2. **Per-tenant** — disable the Agent for specific workspaces from **Insight → Audience**.
3. **Globally** — turn off the Agent from **Agent → Configuration**.

Hiding takes effect immediately; no page reload required.

## Next steps

<CardGroup cols={2}>
  <Card title="Train on your docs" icon="book-open" href="/agent/train">
    Add your first knowledge source.
  </Card>

  <Card title="Publishing workflow" icon="git-branch" href="/agent/publishing">
    Stage and preview before going live.
  </Card>
</CardGroup>