Styling the chat widget

Where styling comes from

The chat widget reads style in two layers and merges them at init time:

Dashboard styles — fetched from https://api.appgram.dev/api/v1/projects/{id}/chat-widget/style. Edited via Settings → Chat widget in your AppGram dashboard. This is the "live" layer — changing it updates every embed on next page load without needing a code change.
Inline settings — set on the script tag (data-* attributes) or on window.appgramChatSettings. Always wins on a per-key basis.

Set the canonical look-and-feel in the dashboard, then override individual keys per embed when you need a one-off variation (A/B tests, staged rollouts, white-label deploys).

To opt out of the dashboard fetch entirely and manage everything inline, set data-auto-fetch-style="false".

The color palette

The widget uses fourteen color tokens. Each token has a light-mode and dark-mode value; the active palette is picked by the color mode setting (light, dark, or auto — which follows the visitor's OS).

Surface tokens

background — the panel's base fill behind everything.
hero_background — the upper "greeting" section on the Home tab.
card_background — cards inside the panel (release cards, source citations, etc.).
tab_bar_background — the bottom tab bar fill.
border — separators between sections.

Text tokens

foreground — primary text colour.
muted_foreground — secondary text (timestamps, metadata, descriptions).

Brand / accent tokens

accent — primary brand colour. Drives the launcher, the active tab indicator, links, and the user message bubble.
accent_foreground — text and icons rendered on top of accent-coloured surfaces (e.g. the launcher icon).
user_message_background — the visitor's own message bubbles. Defaults to accent.
user_message_text — text inside user bubbles.
launcher_background — the floating launcher button fill.
launcher_icon_color — the launcher's chat-bubble icon.
glow_color — the soft wash behind the Home hero. Use a tinted accent for a "spotlit" feel, or set to "transparent" to flatten the look.

Light + dark mode

Each token is set independently per palette. The dashboard's Smart invert button channel-flips the surface and text tokens (white ↔ black, mid-greys preserved) while leaving brand colours alone — useful for generating a quick dark palette from a light one without losing your accent.

Setting the inline data-theme attribute forces the palette regardless of the visitor's OS preference: light uses the light palette, dark uses the dark palette, auto picks per OS.

Background style

The panel's body sits over a decorative background layer. Four built-in styles plus an optional image overlay:

None — solid background colour only. Calm, default.
Blur orbs — softly-blurred radial gradients in the accent colour.
Grid — fine line grid; works well on light palettes.
Dots — subtle dot pattern; works on either palette.
Grain — film-grain noise. Adds texture without competing with content.

Background image

Drop a background.image_url in the dashboard and the widget composites it under the pattern. Three image modes:

Cover — fill the panel (may crop). Best for photographs.
Contain — show the full image without cropping. Best for logos or pattern tiles.
Hide image — keep the slot but render the background colour only. Useful when toggling between "branded" and "clean" looks.

Two more knobs:

background.blur (0–40) — gaussian-blur the image. Useful for photographic backgrounds that would otherwise compete with the text.
background.opacity (0–100) — fade the image into the base colour. Anything above ~70% reads as "image-forward"; below ~40% as "tinted accent".

Typography

Font family — pick from the dashboard's preset list (Inter, SF Pro, Helvetica Neue, Georgia, JetBrains Mono) or write a custom CSS font-family stack. Web fonts must be loaded by your host page; the widget doesn't ship its own font files.
Base font size — defaults to 14px. Available via the data-font-size attribute as the named tokens sm / base / lg, or any CSS size literal (e.g. "15px", "0.9rem").

Layout

Position — bottom-right (default), bottom-left, top-right, top-left. The launcher and panel both anchor to this corner.
Visible tabs — pick any subset of home, messages, help, changelog. Useful for trimming the panel when a project doesn't have a help center or a public changelog. Set via the dashboard; can't be set inline.
Default tab — which tab is selected when the panel first opens.

Hero copy

The Home tab's hero is also style territory:

agent_name — the displayed name (also appears in the avatar fallback as its initial).
greeting — the first line ("Hi there 👋", "Hey Sarah,", etc.). Emoji works.
subtitle — the second line.
options — pipe-separated quick-reply buttons rendered as a list under the hero.
team_avatars — comma-separated avatar URLs shown as a stacked row above the hero, hinting "real humans are reachable".
logo_url — single avatar / logo shown when the assistant is named generically (e.g. "Help").

Worked example — match your brand in five settings

For most projects you only need to set five things to look on-brand. From the dashboard:

Accent = your primary brand colour. Drives launcher, links, and user bubbles.
Font family = whatever your marketing site already uses.
Background style = pick "Blur orbs" for a soft, branded feel, or "None" for a clean Stripe-style look.
Color mode = auto so it follows the visitor's OS.
Greeting and subtitle = swap the defaults for something on-voice.

Everything else has sensible defaults that adapt to your accent and mode automatically.

Live preview

The dashboard's chat-widget editor renders a live preview that loads the same CDN bundle the embed uses, so what you see in the preview is exactly what your visitors will get on next page load. Use the preview's mode toggles to spot-check both light and dark palettes before saving.

Inline overrides — quick reference

Any of these can be set as a data attribute on the script tag without touching the dashboard:

data-accent-color — overrides the accent.
data-theme — forces light / dark / auto.
data-position — overrides the launcher corner.
data-font-size — overrides the base font size.
data-default-tab — opens a different tab first.
data-greeting / data-subtitle / data-agent-name / data-logo-url — overrides hero copy.
data-options — pipe-separated quick replies.
data-team-avatars — comma-separated avatar URLs.
data-auto-fetch-style="false" — disables the dashboard fetch entirely.

For the full per-token palette and background image controls, edit them in the dashboard — the embed picks them up automatically.