Widget customization

The widget's appearance and behavior are set per site in the dashboard (open Sites, then the site's widget settings). Because the widget downloads its settings each time it loads, you never need to change the embed snippet when you change them. Settings are cached briefly, so allow up to a minute for a change to reach visitors.

This page documents every setting, using the names stored in the configuration so that they match what you see in the dashboard, exports and the config response of the public API. Everything here is public: do not put secrets in any of these fields.

Theme#

When the widget is in dark mode (set to dark, or auto with a visitor whose device prefers dark), the window background, main text, and AI and operator bubble colors are replaced by a built-in dark palette; your primary and visitor bubble colors still apply, so choose ones that work on both, or set the dark colors yourself in the dark group (see advanced settings below). Colors must be six-digit hex values such as #1f7a5a; anything else is replaced by the default. Always check contrast: text on primary should have a contrast ratio of at least 4.5:1 for readability.

Window#

Launcher#

The launcher is the round button that opens the chat.

Header and persona#

Edit the subtitle if you do not reply instantly outside business hours. Set honest expectations.

Text and labels (copy)#

Every piece of text the widget shows can be changed, which is how you translate it or adapt the tone. Each is limited to 120 characters except the error and consent text, which allow 300.

The agent's own greeting and conversation starters are part of the agent, not the widget, so they are edited in the agent builder. To run the chat in several languages, set the agent's language to auto so it answers in the visitor's language; the labels above stay in the single language you set. Per-language label sets are not available in v1.

Behavior#

If no trigger is configured, auto_open opens the chat immediately when enabled, so always set at least a delay, a scroll depth or exit intent.

Page rules#

Page rules control which pages show the widget, without editing your website. Add URL path patterns to include (show only on matching pages; if empty, show everywhere) and exclude (never show on matching pages). The asterisk * matches any characters. Up to 30 patterns each, 200 characters per pattern.

{
  "page_rules": {
    "include": [],
    "exclude": ["/checkout*", "/account/*", "/legal/*"]
  }
}

To show different agents in different sections of the same site, use page targeting on the agents themselves: see Idle follow-ups and page targeting. Site-wide page rules and agent targeting combine: the widget must be allowed by both.

Page events#

The Page events section lets your own code trigger widget actions without writing widget code. Each rule has an event name and any of: open the chat, show a short message above the chat button, set visitor attributes (values can use {{field}} from the event data). Fire it with SiteTrellis('event', 'name', {...}). See Auto-open, exit intent and consent for the rules and limits.

Mobile and accessibility#

• Mobile. With mobile_fullscreen on, the chat fills the screen on phones, which gives room for the keyboard. Use hide_on_mobile if the launcher covers important buttons on your mobile layout. The mobile.layout setting also offers a bottom sheet or a small floating window, and the optional expand button gives phones a true full-screen view that respects the notch and the on-screen keyboard.
• Keyboard and screen readers. The widget is built to be keyboard operable: the launcher and controls can be reached with Tab, the window can be closed with Esc, focus moves into the chat when it opens and returns to the launcher when it closes, and new replies are announced through a live region. Test with your own assistive technology, since page context matters.
• Contrast and motion. Choose theme colors with sufficient contrast. The widget respects the visitor's reduced-motion preference where animation is used.

Advanced appearance settings#

Beyond the basics above, the widget has a structured settings document (schema 2). Every group is optional: a group you never touch keeps the look it always had, so sites saved before these settings existed render exactly as before. In the dashboard they are grouped in the Appearance tab, with search, a live preview and per-section reset. All values are validated on the server and again in the widget: colors are six-digit hex, choices come from fixed lists, numbers are clamped to a range, URLs must be https://, and nothing is ever treated as HTML.

The extra text settings are footer_note (a line above "Powered by"), expand_label and collapse_label (the tooltip and screen reader name of the expand button), close_label (used by the text close button), side_title (the heading of the side panel in the expanded view, default "Ask about") and typing_text (the text typing indicator). Like every label they accept up to 120 characters (the footer note 160).

Check contrast as you go: the editor shows the WCAG ratio next to each text color, in light and in dark mode, and warns below 4.5:1. All premade themes pass AA in both modes.

Going further#

• Start from one of fourteen designed themes and use the larger, mobile friendly view: Themes and the expanded view.
• Fine-tune styling on Pro and above: Custom CSS and Shadow DOM.
• Open the chat from your own buttons and pass user details: Widget JavaScript API.
• Control where the widget loads: Install on any website.