Widget Appearance

The appearance of a web widget is a preset plus your overrides. A preset sets the full look. An override changes one value, such as the accent colour or the panel corners. Each value that you do not override comes from the preset. You set the appearance on the dashboard. The platform stores it with the widget, and each site that shows the widget gets it. The page that shows the widget cannot change the theme at run time.

Open the appearance editor

Open the widget

Go to Agent > Points of Contact > Web Widgets and click the widget.

Open the editor

On the Appearance card, click Customize. You need the web-widgets:update permission.

Change the look

Select a preset, then change the values on the tabs. The live preview shows each change.

Save

Click Save. To discard your changes, click Cancel.

When the editor is closed, the Appearance card shows a picture of the widget and a summary: Preset, Light or dark, Accent, Font and Launcher.

Presets

The editor shows the presets in a gallery. Click a preset to select it.

The seven presets in a gallery. Classic is selected (dark) — The preset gallery in the appearance editor

Preset	The look
Classic	The widget’s first look: an accent header, rounded bubbles and a soft shadow. This is the default.
Glass	Translucent panel that blurs the page behind it, with a glossy accent header.
Plain	The browser’s own look: serif text, plain lines, no shadow and no bubbles.
Swiss	International style: black rules, square corners and one strong red.
Bauhaus	Primary colours, a black outline and a hard offset shadow.
Paper	Serif text on warm paper, ink-blue accents and letter-like outlined bubbles.
Terminal	A dark console in both schemes: monospace text, phosphor green and hard edges.

Each preset meets the WCAG 2.1 AA contrast ratio (4.5:1) for its text, in light and in dark.

The chat panel of the widget with the Glass, Bauhaus and Terminal presets, side by side (light) — Three presets in the full-window sample tab: Glass, Bauhaus and Terminal

The chat panel of the widget with the Glass, Bauhaus and Terminal presets, side by side (dark) — Three presets in the full-window sample tab: Glass, Bauhaus and Terminal

Above the gallery, the editor shows the number of overrides, for example “3 overrides on the preset”. Click Clear overrides to remove all overrides and use the preset as it is. When you select a different preset, your overrides stay.

Light or dark

Light or dark sets which colour scheme the widget shows:

As the visitor’s system — the widget follows the light or dark choice of the visitor’s device.
Light — always light.
Dark — always dark.

Overrides

The overrides are on five tabs: Colours, Shape, Type, Surface and Launcher. Each field shows its default value in grey when you do not override it. The hint below the field tells you where the default comes from, such as From the preset. To remove an override, click the reset icon beside the field label (tooltip Use the default).

Colours

The Colours tab has a Light tab and a Dark tab, because each scheme has its own colours. A scheme that the widget does not show has “(not shown)” after its name.

Group	Colours
Accent	Accent, Accent text
Panel	Background, Surface, Text, Muted text, Border
Header	Header background, Header text
Messages	Visitor bubble, Visitor bubble text, Agent bubble, Agent bubble text

Type a colour as #rrggbb, or as #rrggbbaa for a colour with transparency. You can also click the colour well and pick a colour.

Where the default colours come from

Accent — the Primary colour of your tenant, if your tenant has one. Otherwise, the accent of the preset. You set the Primary colour in Settings > Theme > Brand colours. See Theme.
Accent text — near-black or white, whichever has more contrast on the accent.
Header text, Visitor bubble text and Agent bubble text — the text colour of the preset. If you override the background of the header or a bubble, its text becomes near-black or white. The platform selects the one with more contrast.
In some presets, such as Classic, the header and the visitor bubbles follow the accent. When you change the accent, they change too.
All other colours come from the preset.

Contrast warnings

The editor checks the contrast of each text colour on its background, in light and in dark:

Text on Background
Muted text on Background
Header text on Header background
Visitor bubble text on Visitor bubble
Agent bubble text on Agent bubble
Accent text on Accent

When a pair has a contrast of less than 4.5:1, the Colours tab shows a red count. The tab also shows the message “Some text may be hard to read” with a list of the pairs. You can still save, but visitors with low vision can find the text hard to read.

Shape

Field	Values
Panel corners	0 to 32 px
Message corners	0 to 32 px
Button and field corners	0 to 32 px
Border width	0 to 4 px
Border style	Solid, Dashed, Double

Type

Field	Values
Font	See Fonts.
Text size	13 to 18 px
Spacing	Compact, Comfortable

Surface

Field	Values
Shadow	None, Soft, Strong, Hard offset
Background blur	0 to 40 px
Panel opacity	0.5 to 1
Header	Filled, Plain, Underline
Messages	Filled, Outlined, Plain

A Panel opacity of less than 1 makes the panel translucent. The panel then blurs the page behind it.

Launcher

Field	Values
Corner	Bottom right, Bottom left
Distance from the side	0 to 64 px
Distance from the bottom	0 to 64 px
Shape	Circle, Pill, Square, Rounded
Size	Small (48 px), Medium (56 px), Large (64 px)
Style	Solid; Glass, which blurs the page behind it; Orb, a sphere in the accent colour that turns
Icon	Chat bubble, Spark, No icon
Animation	None, Pulse, Orbit
Label	A short text beside the icon. Leave it empty to show the icon only.

A Circle launcher shows no label. If you set No icon and no label, the launcher shows the chat bubble icon. The Orb style and the animations stop when the visitor’s device asks for reduced motion.

Fonts

On the Type tab, select the kind of font in Font:

Kind	What it does
The preset’s font	The system font of the preset. Nothing loads. This is the default.
A system font stack	A font that each device has. Select the Stack: Sans serif, Serif, Monospace or Rounded. Nothing loads.
Fonts on the visitor’s device	Type Font names, separated by commas, such as `"Segoe UI", Arial`. The widget uses a font only when the visitor’s device has it.
A web font stylesheet	A CSS file that loads a web font, such as a Google Fonts stylesheet. Type the Family name and the Stylesheet URL.
Font files	Your own font files. Type the Family name, then add a Font file URL, a Weight and a Style for each file.

Web font stylesheet

Example of a Stylesheet URL:

https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap

The Family name for this example is Inter.

The Type tab. Font is A web font stylesheet, the family name is Fraunces, and the live preview shows the Fraunces font (light) — The Type tab with a Google Fonts stylesheet for the Fraunces font

The Type tab. Font is A web font stylesheet, the family name is Fraunces, and the live preview shows the Fraunces font (dark) — The Type tab with a Google Fonts stylesheet for the Fraunces font

When you save, the server reads the stylesheet. It finds the hosts of the font files in the stylesheet. The widget then lets the chat panel load fonts only from the stylesheet host and these font hosts. The stylesheet must obey these rules:

The URL starts with https:// and names a public host.
The server gets an answer of type text/css.
The stylesheet names at least one font file on a public https host.
The font files are on a maximum of 8 hosts.

If the server cannot use the stylesheet, the field shows “The server cannot use this stylesheet.” and the reason. The Type tab then shows a warning icon.

Font files

Each font file must be woff2, woff, ttf or otf, with an https URL on a public host. Add one file for each weight and style that you need, to a maximum of 8 files. Example: https://cdn.example.com/brand-400.woff2.

The launcher is on your own page, and the widget does not load a font into your page. The launcher uses the family name of the theme font. If your page does not load that font, the launcher shows the system font.

Live preview

While the editor is open, the Live preview shows the sample site beside the controls, with your unsaved changes. The preview changes a short time after each change. The Open the sample site in a new tab icon button opens the preview in a new browser tab. There, the widget has the full window. The tab shows your unsaved changes. When you make more changes, the tab shows The theme has changed. and a Reload button. The tab can show these messages:

Message	What it means
The theme has changed.	Click Reload to see the latest version.
The editor is closed, so there is no draft. Reload shows the saved theme.	You saved or cancelled the edit.
The preview expires soon. / The preview has expired.	A preview lasts 10 minutes. Click Reload to make a new one.
No draft is open, so this tab shows the saved theme.	The tab shows the saved appearance.

Save

Click Save to store the appearance. Each site gets the new appearance:

A page that a visitor opens after the save shows the new look.
A page that stays open shows the new launcher after a maximum of 30 minutes.

If another person saves the appearance while you edit it, a bar asks which version to keep. Click Use theirs or Keep mine.

Style the launcher from your page

The launcher and the panel frame are in a closed shadow root, so the CSS of your page cannot reach them. Your page can style these parts with the ::part() selector on the element [data-dialai-widget]:

Part	What it is
`launcher`	The launcher button.
`launcher-icon`	The icon in the launcher.
`launcher-label`	The label in the launcher.
`badge`	The count of unread messages.
`panel`	The panel that holds the chat.
`panel-close`	The close button of the panel, before the chat loads.

These part names do not change. Example:

[data-dialai-widget]::part(launcher) {
  box-shadow: 0 0 0 3px #ffd400;
}
[data-dialai-widget]::part(launcher-label) {
  letter-spacing: 0.04em;
}

The chat itself is in an iframe on a different origin. No CSS of your page reaches it, and the host page has no theme option. Only the appearance that you save on the dashboard changes the chat.

Best practices

Practice	Reason
Start from the preset that is nearest to your site.	You need fewer overrides.
Set the Primary colour of your tenant before you override the accent.	All widgets then use your brand colour.
Correct each contrast warning before you save.	Some visitors cannot read text with low contrast.
Use As the visitor’s system when your site has a dark mode.	The widget then follows the visitor’s choice.

Web Widgets

Create a widget and put it on your site.

Signed-in visitors

Tell the widget who your customer is.

Theme

Tenant logos and brand colours.

Get Started

Monitoring

Building & Managing Flows

Docs

Agent

Outbound

Integrations

Settings

Open the appearance editor

Presets

Light or dark