Advanced Customization
Deeper widget theming — colour and brand-asset tokens, and white-label.
Audience: Logged-in customers.
This is the deep reference for theming the widget — the appearance tokens you can set, how the Light/Dark system works, and how to remove our branding (white-label). It complements the walkthrough in Customizing the chat widget; if you just want the tour of the customizer screen, start there and come back here when you need the details.
The settings on this page live in Dashboard → Chat Configuration — no code, no CSS, and no re-pasting your embed snippet. You do not inject raw CSS: instead of a stylesheet, the widget exposes a structured appearance-token system, so your brand colours survive theme switches and translations.
Each website has its own appearance configuration — to theme a different site, pick it in the workspace switcher at the top of the left-hand navigation, under the logo. For a paid site of your own, the plan badge on the switcher shows that site's plan, and Plan availability below says which tokens that plan can set.
Plan availability
The table below lists the widget's behaviour and appearance settings with the plans that unlock each one. The Theme Appearance section behaves as one unit: it shows a single padlock overlay — naming the plan that unlocks it, with an upgrade shortcut — until your plan grants every token in it, rather than letting you set some tokens and not others.
The table is generated from the plan catalogue our own servers read, so it says what your plan actually unlocks rather than what a page was last edited to claim.
| Setting | Where it lives | Starter | Pro | Business |
|---|---|---|---|---|
| Language | Behavior | ✓ | ✓ | ✓ |
| Default Theme | Behavior | ✓ | ✓ | ✓ |
| Auto Show Chat | Engagement | — | ✓ | ✓ |
| Auto Show Delay (s) | Engagement | — | ✓ | ✓ |
| Bubble Position | Bubble Geometry | — | ✓ | ✓ |
| Bubble Size | Bubble Geometry | — | ✓ | ✓ |
| Bubble Offset Bottom | Bubble Geometry | — | ✓ | ✓ |
| Bubble Offset Side | Bubble Geometry | — | ✓ | ✓ |
| Bubble Text | Bubble Text | ✓ | ✓ | ✓ |
| Show Bubble Text | Bubble Text | ✓ | ✓ | ✓ |
| Bubble Color | Theme Appearance | — | — | ✓ |
| Bot Avatar | Theme Appearance | — | — | ✓ |
| Widget Logo | Theme Appearance | — | — | ✓ |
| Custom Bubble Icon | Theme Appearance | — | — | ✓ |
| Remove "Powered by" | White Label | — | — | ✓ |
| Background Color | Theme Appearance | — | — | ✓ |
| Accent Color | Theme Appearance | — | — | ✓ |
| Text Color | Theme Appearance | — | — | ✓ |
| Header Color | Theme Appearance | — | — | ✓ |
| User Message Color | Theme Appearance | — | — | ✓ |
| Bot Message Color | Theme Appearance | — | — | ✓ |
| Background Image | Theme Appearance | — | — | ✓ |
A locked section still shows you what's inside and which plan unlocks it — see Billing & plans for how upgrades work.
Theme Appearance — how theming works
Theming lives in a single Theme Appearance section of 11 tokens — 4 image (URL) tokens and 7 colour tokens. There is no free-form CSS field; the tokens map to the widget surfaces listed in the tables below.
The two things that make this system reliable:
- Per-theme variants. The Light and Dark themes keep separate values for the tokens. A visitor sees whichever theme matches their system preference, so a colour that reads well on white might need a different value on a dark background. You set each theme separately.
- Sensible fallback. If you leave a token empty, the widget falls back to its own default for that theme — never to the opposite variant. So a blank Dark value doesn't accidentally pull in your Light colour; it uses the widget's built-in dark default.
One token bends that on the welcome screen: with Bot Avatar empty, the agent's avatar there shows your Widget Logo for the same theme if you've set one, and the built-in mark if you haven't. In the header, an empty Bot Avatar shows no avatar. Set Bot Avatar when you want the agent to look like something other than your company mark.
Light / Dark variant tabs
At the top of the section are two tabs — Light Theme and Dark Theme. Switch between them to edit each variant's values. A small dot on a tab means that variant already has at least one custom value, so you can tell at a glance whether you've themed both modes.
With Default Theme set to Auto-detect, the live preview follows your dashboard's light/dark theme, so flip the dashboard theme to check how each variant reads before you save.
"Apply to both"
Every token has a Both button. Click it to copy the value from the tab you're on into the other theme, so you don't have to type the same brand colour or logo URL twice. It stays greyed out while the field you're on is empty.
Clearing one token
Each colour token carries a small Reset to default control, which appears once that field has a value. It clears that token on that theme only and hands the surface back to the widget's built-in colour — the quickest way to undo one experiment without touching the rest of your palette. It is not the same as the Reset button at the bottom of the screen, which returns the page to its last saved state.
Image tokens (URLs)
The token grid shows the four image tokens first. Provide a publicly reachable HTTPS URL for each image you want to use — host the asset on your own site or CDN and paste the link. There is no upload here; the widget loads the image from the URL you give.
| Token | Where it shows |
|---|---|
| Widget Logo | The logo in the widget's header (replaces the default brand mark + name) |
| Bot Avatar | The agent's avatar in the widget header (beside the logo or name) and on the welcome screen |
| Bubble Icon | A custom icon on the floating launcher button, instead of the default brand mark |
| Background Image | A full-bleed background behind the chat panel |
Which plan unlocks each of these is in Plan availability above.
Tips:
- Use a transparent PNG or SVG for the logo and bubble icon so they sit cleanly on your header and launcher colours.
- Keep the background image subtle and low-contrast — chat text renders on top of it, and a busy image hurts readability. Pair it with a Text Color that stays legible over your image.
- Set the value on both Light and Dark tabs (or use Both) if you want the same asset in both modes; otherwise supply a light-optimised and a dark-optimised version per tab.
Colour tokens
Below the image tokens, seven colour tokens cover the widget's palette. Each is a colour picker with a matching hex field, so you can pick visually or paste your brand hex. Pasted values must be the full six-digit form (#1F2937) — the three-digit shorthand and eight-digit values with an alpha channel are refused. Like the image tokens, each has independent Light and Dark values.
| Token | What it colours |
|---|---|
| Bubble Color | The floating launcher button's fill |
| Background Color | The chat panel background |
| Accent Color | Buttons, links, interactive highlights, and the send button gradient |
| Text Color | The foreground text colour |
| Header Color | The widget's top bar |
| User Message Color | The visitor's own outgoing message bubbles |
| Bot Message Color | The assistant's incoming message bubbles |
These seven, the three brand-asset URLs and the background image make up Theme Appearance, which unlocks as one unit — see Plan availability for the plan that does it.
Accent does more than you'd expect. The accent colour flows into the send button's gradient and the interactive highlights throughout the chat — pick one that contrasts with your background so calls-to-action stand out.
White-label — remove "Powered by"
Which plans unlock this control is in Plan availability above, with the other widget settings.
Turn on Remove the “Powered by” badge to hide the branding footer at the bottom of the widget, so it reads as fully native to your brand. It's a single toggle in the White Label section of Dashboard → Chat Configuration, and it flips the branding footer in the live preview immediately.
This is a per-website setting — enable it on the sites where you want a clean, unbranded widget and leave it off elsewhere.
White-label covers the widget footer attribution. It does not replace the logo, avatar, or colours — those are the appearance tokens above. Combine a Widget Logo, a matching Accent Color, and white-label for a widget that looks entirely your own.
See it before you ship — the live preview
The right-hand pane of Chat Configuration is a mock of the embedded widget that re-renders as you type — your logo, the bubble icon on the launcher, the launcher colour, the header, the accent (buttons, links, and the send button), your text and background colours, and the white-label toggle update it at once. A token with no value in the theme it shows previews as the widget's default for that theme, as on the real widget. It carries a Preview badge (and a "Reflects unsaved changes" note) so it is not mistaken for the real embedded widget.
Four tokens are deliberately outside the mock: Bot Avatar, Background Image, User Message Color and Bot Message Color. The preview pane does not show them. That is the preview being narrower than the widget, not the value failing to save — check those four on the real widget after you save.
The preview shows the theme your Default Theme setting picks: Light or Dark as set, and with Auto-detect it follows your dashboard's light/dark theme, standing in for the visitor's system preference. That is why the tokens are split by variant: with Auto-detect, flip the dashboard theme to preview the matching bundle, and confirm both modes look right before you save.
Changes go live when you Save changes; Reset discards edits back to the last saved state. The widget picks up the new theme as soon as you save, through the same embed snippet, and visitors who already have the chat open see it after they refresh. For the full save/propagation behaviour, see Customizing the chat widget.
Related customization
Advanced theming is one piece of a per-website configuration. The rest lives in dedicated guides:
- Greeting, suggested questions, bubble geometry, and behaviour — in the same customizer screen. See Customizing the chat widget.
- The agent's persona, tone, and guardrails (its voice, as distinct from its look) — see AI Templates.
- Voice input and spoken replies (speech-to-text / text-to-speech) — see Voice Features.
- Lead-capture forms, webhooks, Slack delivery, scheduling, and custom actions — see Capturing Leads and Integrations.
Need help getting a look right, or have an advanced use case not covered here? Email support@novixagent.ai — we're happy to help you dial it in.