Appearance and branding

The Theming tab of the Widget Builder controls how the widget looks: the launcher button, the chat window, per-mode colors, and where the widget sits on the page. Everything you set here is stored under config.v1 on the widget. You can also auto-brand from a domain, which pulls colors and logos from your website and writes them into the same fields. This page is a reference for the appearance fields. For the message text, default mode, and quick actions, see Text, voice, and quick actions. To create the widget in the first place, see Creating a widget.

Editing appearance requires the web_widgets:manage scope. web_widgets:read is view-only.

Theme

The Theme select decides which color scheme the widget renders in.

Value	Behavior
`system`	Follow the visitor’s OS or browser preference. This is the default.
`light`	Always render in light mode.
`dark`	Always render in dark mode.

The value is stored at config.v1.theme.

Colours

Colors are defined separately for Light Mode and Dark Mode so the widget looks right in either theme. Each mode exposes the same four tokens.

UI label	Used for	`config.v1.chat` path
Primary Background	User messages, active states	`<mode>.background_color.user_message`
Primary Text	User message text	`<mode>.text_color.user_message`
Secondary Background	Send button, controls	`<mode>.background_color.controls_button`
Secondary Text	Input text, icons	`<mode>.text_color.controls_button`

<mode> is light_mode or dark_mode. Each is a theme object with background_color and text_color maps. Leave a token empty to fall back to the built-in default for that mode.

Surfaces like the message background, header, input, and agent response text are fixed neutral colors and are not themed by these four tokens.

Launcher button

The launcher is the floating button visitors click to open the widget. Its fields live under config.v1.trigger.

UI label	Field	Type	Default	Description
Shape	`shape`	`circle` \| `square`	`circle`	Setting the shape also sets `chat.avatar_shape` to match.
Size	`size`	number (px)	`56`	Presets: XS `40`, S `48`, M `56`, L `64`, XL `72`. Each preset also sets a matching `padding`.
Button Background	`backgroundColor`	string	—	Hex color for the launcher background.
Padding	`padding`	number (px)	`~20%` of size	Space between the button edge and the avatar. Slider range `0`–`50`.
Use Avatar	`avatarUrl`	string	—	Toggle on to upload a launcher image. When off, a default icon is shown.

Per-mode launcher overrides

By default the launcher uses the single backgroundColor and avatarUrl. Toggle Override dark mode or Override light mode to set mode-specific values under trigger.dark and trigger.light. Each override block accepts:

Field	Description
`backgroundColor`	Launcher background for that mode.
`textColor`	Launcher text/icon color for that mode.
`avatarUrl`	Launcher avatar for that mode.

When a mode override is set, it takes precedence over the top-level backgroundColor and avatarUrl for that mode.

Chat window

Turn on Use Avatar under Chat window to give the agent a custom avatar inside the open chat. You upload a Light Avatar (chat.avatar_url) and an optional Dark Avatar (chat.dark_avatar_url). When the chat avatar is disabled, the chat window falls back to the launcher avatar, or to the default Orb.

Position

The launcher is anchored to the bottom-right corner. Set its offsets in pixels under config.v1.position.

UI label	Field	Default	Description
Right	`position.right`	`24`	Distance from the right edge, in pixels. Minimum `0`.
Bottom	`position.bottom`	`24`	Distance from the bottom edge, in pixels. Minimum `0`.

config.v1 structure

All appearance and content settings live under config.v1. The relevant shape:

{
  "v1": {
    "theme": "system",
    "position": { "right": 24, "bottom": 24 },
    "trigger": {
      "shape": "circle",
      "size": 56,
      "padding": 12,
      "backgroundColor": "#18181B",
      "avatarUrl": "https://.../launcher.png",
      "dark":  { "backgroundColor": "...", "textColor": "...", "avatarUrl": "..." },
      "light": { "backgroundColor": "...", "textColor": "...", "avatarUrl": "..." }
    },
    "chat": {
      "name": "Support",
      "avatar_url": "https://.../avatar-light.png",
      "dark_avatar_url": "https://.../avatar-dark.png",
      "avatar_shape": "circle",
      "welcome_title": "Hi there",
      "welcome_description": "How can we help?",
      "start_button_text": "Start chat",
      "privacy_policy_url": "https://example.com/privacy-policy",
      "disable_powered_by_anyreach": false,
      "light_mode": {
        "background_color": { "user_message": "#...", "controls_button": "#..." },
        "text_color":       { "user_message": "#...", "controls_button": "#..." }
      },
      "dark_mode": {
        "background_color": { "user_message": "#...", "controls_button": "#..." },
        "text_color":       { "user_message": "#...", "controls_button": "#..." }
      }
    }
  }
}

The chat object also holds content fields that are not part of the Theming tab:

Field	Type	Description
`name`	string	Agent name shown in the chat header.
`welcome_title`	string	Heading on the pre-chat screen.
`welcome_description`	string	Subheading on the pre-chat screen.
`start_button_text`	string	Label on the button that opens the chat.
`privacy_policy_url`	string	Link shown at the bottom of the chat.
`disable_powered_by_anyreach`	boolean	When `true`, removes the “Powered by Anyreach” footer.

See Text, voice, and quick actions for the content and mode fields.

Auto-Brand

Auto-Brand fills in colors and logos from a domain so you do not have to set them by hand. Enter a domain in the Auto-Brand box at the top of the Theming tab and fetch it. Anyreach looks up the domain through brand.dev and applies the result to config.v1.

Enter a domain

Type your website domain (for example example.com) and run the fetch. The protocol, www., and a trailing slash are stripped automatically.

Anyreach retrieves the brand

The platform calls brand.dev for that domain and returns the brand’s logos, colors, company info, and social links.

Values are applied to config.v1

The fetched data is merged into the current config. Review the result and click Save changes to keep it.

What Auto-Brand sets

Source from brand.dev	Applied to
First brand color	`trigger.backgroundColor`, and `user_message` / `controls_button` backgrounds in both `light_mode` and `dark_mode`
Contrast of the first color	`user_message` / `controls_button` text colors in both modes (black or white, whichever is readable)
`icon` logo, else `light` logo	`chat.avatar_url`
`dark` logo	`chat.dark_avatar_url`
—	`theme` is set to `light` and `trigger.padding` is set to `14`

Auto-Brand overwrites the color and avatar fields above. Other fields, such as name, welcome_title, and your launcher size and position, are preserved.

Endpoint

The Theming tab calls this endpoint behind the scenes. You can call it directly to fetch brand data for a domain.

curl -X POST https://api.anyreach.ai/core/web-widgets/{id}/auto-brand \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

The body takes a single domain field. The response is the brand object (logos, colors, company, socials) from brand.dev. The endpoint requires the web_widgets:manage scope. Applying that response to config.v1 happens client-side; the endpoint itself only fetches the brand data.

Replace {id} with the widget ID. User personal access tokens (pat_) must also send X-Anyreach-Org; organization API keys (ak_) carry their org implicitly and omit it.

​Theme

​Colours

​Launcher button

​Per-mode launcher overrides

​Chat window

​Position

​config.v1 structure

​Auto-Brand

​What Auto-Brand sets

​Endpoint

​Next steps

Text, voice, and quick actions

Creating a widget

Theme

Colours

Launcher button

Per-mode launcher overrides

Chat window

Position

config.v1 structure

Auto-Brand

What Auto-Brand sets

Endpoint

Next steps