Customization

Theme the chat bar and the chat panel, write what the widget says, and choose whether visitors can attach images.

Agent > Customization is where you decide how the widget looks, what it says, and how it behaves on your site. It covers both surfaces: the chat bar, the input that sits at the bottom of every page, and the chat panel it opens above it. An app can hold several named themes; exactly one is marked Default and active at a time.

This is a separate surface from Persona: Persona shapes what the agent says in its answers, Customization shapes how the widget looks and what it says on its own.

The chat bar

Your visitors do not see a floating circle any more. They see a bar: an input, in the middle at the bottom of the page, that says what to do and invites typing. Tapping it opens the chat panel directly above it.

The bar rests small. Before anyone uses it, it is a short pill carrying an ARCY mark and your placeholder, at a resting width you choose. Tapping it, or simply typing into it, widens it to full width and opens the panel above. Clicking anywhere else on your page collapses it back to the pill, so a visitor never has to hunt for a way out. The one exception is while a flow is running: the bar is that flow's status surface, and a stray click must not take it away mid-run.

Three more things follow from that, and they are worth knowing before you theme anything:

The bar never moves. It cannot be dragged, and it is not draggable by your visitors either. It sits bottom centre, and you can raise it off the bottom edge to clear a cookie banner or your own sticky footer.
Open, the bar and the panel are always the same width and share a centre line. There is one width setting, and both read it. They cannot be configured out of line with each other. The resting pill has its own width setting, because there is no panel above it to line up with.
The bar is the only place a visitor types, whether the panel is open or closed. There is no second input inside the panel.

While a flow is running, the panel collapses and the bar becomes the flow's status surface: the flow's name, which step it is on, and a Stop control, while your visitor watches your own product being driven.

Customization > Settings holds three separate uploads, side by side, each saving the moment you choose a file:

Chat header logo: the mark at the top of the chat panel.
Welcome screen icon: the mark shown above the greeting on the welcome screen.
Chat bar icon: the small mark on the left of the chat bar's input, on both the welcome screen and the chat panel.

All three take a PNG, JPEG, WEBP, or SVG file up to 5MB. An SVG stays sharp at every size, so it is the better choice for a logo if you have one.

None is your app icon. That icon is a square tile your own team sees in the sidebar; these three are read by your customers on your site, and a wordmark that suits one rarely suits the others. With none uploaded, the header shows your app's name, the welcome screen shows ARCY's default mark, and the chat bar shows ARCY's default sparkles mark. None falls back to your app icon, and the three do not fall back to each other: they render at different sizes and against different backgrounds, so one upload standing in for more than one of them would often look wrong in at least one place.

What a visitor sees under each message

Every message carries the time it was sent, in the visitor's own clock format. Under each of the agent's answers there is a thumbs up and a thumbs down. A visitor can press one, swap to the other, or press the same one again to take their rating back.

Ratings are anonymous and they are not a support ticket. They arrive as Pulse signal, so a run of thumbs down on one topic tells you where the agent is weak. Nothing about a rating is shown back to the visitor, and there is no reply box: this is a signal, not a conversation.

The gallery

Each theme renders as a card with a live preview and, for admins, a menu:

Make default: activates it. Hidden if it's already the active theme.
Rename: a Name field, up to 100 characters.
Edit: opens the token editor below.
Delete: permanent, with no archive. Disabled while the theme is active, and disabled when it is the only theme left; every app keeps at least one.

Non-admin members see the gallery read-only, with no menu.

Each card's preview is a small 4:3 canvas showing a live conversation, so you can judge a theme's bubbles and colors at a glance without opening it. Inside the editor, the Live preview is a larger 16:9 canvas standing in for a 1920x1080 screen, and you can switch it between every surface your visitors see: the bar on its own, the welcome screen, a conversation, Recent chats, Flows, and the bar while a flow is running.

Texts

Below the gallery, the Texts card holds everything the widget says on its own:

Welcome message: the greeting on the welcome screen. Leave it empty to show none.
Welcome headline: the line above the greeting. Keep it short.
Input placeholder: the hint inside the bar before the visitor types.

All of them are app-level, not per theme: switching theme never changes what the widget says. All of them accept Liquid, the same way Persona fields do, so Hi {{ user.first_name }}! greets a signed-in visitor by name. Type {{ in a field and a list of your attributes opens, filtered by whatever you type next; Insert attribute above the field does the same without typing. An attribute shows in the field as a single highlighted chip rather than raw braces, and one press of Backspace or Delete removes the whole reference.

Write words around the tag, not the tag on its own. A visitor who was never identified, or one identified without that attribute, gets nothing where the tag was: {{ user.first_name }} alone leaves the field blank, while Ask a question, {{ user.first_name }} still reads correctly. The placeholder is the one field where this bites, because it is capped at 80 characters and the tag itself spends about twenty of them. If a placeholder does render to nothing, ARCY shows Ask a question... rather than leaving the bar with no hint in it.

All of them are translatable keys (widget.welcomeMessage, widget.welcomeHeadline, widget.inputPlaceholder) on the Localization page; what you write here is the source language.

Everything else the widget says, the drawer titles, the flow status line, the upload errors, the AI disclosure, is ARCY's own and is already translated. You never have to write or translate it.

Starter flows

The Starter flows card decides what a visitor can tap the moment the chat opens. You feature up to five of the flows you have already authored, and tapping one runs it straight away. Nothing is sent to the agent, and no credits are spent, because you already chose where that visitor should go.

Add a flow opens a searchable picker of your flows. A flow needs a public name before it can be featured: that name is what a visitor reads on the pill, and a flow without one never reaches a visitor anywhere.
Drag a row, or use the up and down arrows, to change the order. The first row is the first pill.
Remove takes the flow off the welcome screen. It does not delete the flow, and it does not remove it from the widget's flows list, which keeps listing everything you publish.

Featuring is set once for the app, while publishing stays per environment. A flow you have featured but not published in an environment simply does not appear there, so the card tells you which of your featured flows are not live in the environment you are looking at. That is a warning, not a block: authoring in Staging before Production is the normal way round.

A brand new app has no starter flows, so visitors see your headline and greeting and nothing to tap. Publish a flow and feature it to give them a first move.

The pill labels are the flows' public names, and those are translatable. See Localization.

Settings

The Settings card holds two things that are deliberately not theme values, because a theme can vary by rule and neither of these may:

Visitors can attach images: see Image upload. Off until you turn it on.
Visitors can move the chat bar: off until you turn it on. See below.
Privacy policy URL: your own policy, linked from the widget's bottom strip so visitors know who holds what they type. Must start with https://.

Turning image upload on without a privacy policy URL shows a warning: you would be inviting strangers to send you photographs with no notice attached. The save is still allowed, so you can set them in either order, but do not ship it that way.

Letting visitors move the bar

The chat bar sits at the bottom centre of the page. That is the right place for most sites, and it is where it stays unless you say otherwise, because you laid your page out around it.

Turn Visitors can move the chat bar on and the resting bar grows a small grip at its left edge. A visitor can drag it anywhere on the page, which is useful when the bar is sitting over something they are trying to read or use.

A few things worth knowing:

Where a visitor leaves it is remembered in their own browser, not in your app and not against their account. The same person on a laptop and on a phone gets a different answer, which is the point: it is a property of the window they are looking at.
The chat panel follows the bar. It still opens on the bar, just above it, wherever the bar happens to be.
The grip is on the resting bar only. Once the panel is open, the bar is a composer and the handle would be sitting beside the text a visitor is typing.
Phones are unaffected. On a small screen the bar is already the full width and the panel is a full-height sheet, so there is nowhere to move it to.
Turning it off puts every bar back. Nothing has to be cleaned up: a position a visitor saved is simply no longer read.

The token editor

The editor shows the live preview at the top and three tabs of settings under it. The preview updates as you change values, before you save.

Previewing another language

With two or more locales enabled on the Localization page, the preview's Settings sheet carries the same Language row your visitors get, and the state switcher above the canvas gains a Language button that opens the picker directly.

Switching it previews the whole panel in that language: ARCY's own text, and your own welcome message, headline, placeholder and starter-flow pills, read from the translations you saved on the Localization page. A string you have not translated yet shows in your source language, which is exactly what a visitor in that language would see.

This changes nothing about the theme. It is a way of looking at it, not part of it, and it is not saved.

Shared

Read by both the bar and the chat panel, so the two always match.

Brand colors: Text, Background, Hover, Active. The visitor's own message bubbles, the Send button, and the welcome screen's icon. Hover and Active fall back to Background when empty.
Main colors: Text and Background. The bar and the chat panel body.
Border width (0 to 8px) and Border color: the bar's edge and the panel's, from one value. An empty color uses a faint version of the main text color.
Glassiness (0 to 100): blurs what is behind the bar and the panel and makes their background slightly see-through. Browsers without blur support show them solid, never transparent.
Corner radius: one setting for both the bar and the chat panel, so the two can never drift apart into differently-rounded pieces of what should read as one widget. Five presets from square to a full pill.
Shadow: None, Soft, Medium, Strong, or Bold. Same one-setting-for-both reasoning as corner radius.
Font: 18 choices: five system stacks (System, Serif, Monospace, Humanist, Rounded) that need no download, and 13 web fonts (Inter, Roboto, Open Sans, Lato, Poppins, Montserrat, Nunito, Source Sans 3, Work Sans, DM Sans, Manrope, Playfair Display, IBM Plex Sans) served from ARCY's own servers, never from Google or any third party, and loaded only when the chat panel opens. Latin and Latin Extended are covered, so Turkish renders.
Stacking order (z-index): how the widget stacks against other floating things on your site, such as another chat tool. Higher sits on top. Default 2147483000.

Bar

Resting bar width (180 to 480px): how wide the bar is before anyone opens it. Fixed pixels rather than a share of the screen, because the resting bar is a control and a control should be one shape on every monitor. A placeholder longer than the bar is cut off, the same way it is in the open composer, so widen the bar or shorten the text.
Distance from the bottom (0 to 120px): raise the bar to clear a cookie banner or your own sticky footer.
Chat bar icon size (14 to 28px): the mark on the left of the bar's input. This is its own setting, not the header or welcome icon's: it renders far smaller, inline with the input text. With no chat bar icon uploaded this sizes ARCY's default sparkles mark, so the control stays live either way.

There is no corner radius or shadow here, and no open width. Open, the bar reads the chat panel's width, so the two always line up, and it reads corner radius and shadow from Shared, so it never looks different from the panel above it.

Chat

Width (20% to 50% of your visitor's own screen width): the panel's width and the bar's, once the chat is open. A percentage rather than a fixed pixel size, so the widget scales correctly on every visitor's screen rather than just the one you previewed against.
Max height (30% to 80% of your visitor's own screen height): the panel's height. It takes this height rather than growing with the conversation, so the surface does not change size under your visitor on every message. It still never grows past what the screen has left above the bar.
Header icon size (16 to 48px): the height of your chat header logo. The logo renders at its own natural aspect ratio scaled to this height, not cropped into a square, so a wide wordmark or a non-square icon keeps its shape. With none uploaded, the header shows your app's name instead and this has nothing to size, so the control is dimmed until you add one in Customization > Settings.
Welcome icon size (16 to 72px): the round mark on the welcome screen. This is its own setting, not the header icon's: the two sit on different surfaces at different sizes, so one number could not serve both. With no welcome icon uploaded this sizes ARCY's default mark, so the control stays live either way. It also sizes the docked launcher, the corner button a visitor can shrink the widget to, because that button is this same mark. See Settings.
Assistant bubble: Background and Text for the agent's replies. The visitor's own bubbles use the brand colors. An empty Text uses the main text color.
Scrollbar: Width (2 to 16px), Track, Thumb, Thumb on hover.

What is fixed

The panel header carries Recent chats and Flows on the left, your app logo in the middle (your app name when you have not uploaded one), and a collapse control on the right. There is no close button: the bar never leaves, so collapsing is the only thing that control could mean, and a visitor never has to wonder whether closing lost their conversation.

The panel's bottom strip carries only "Powered by ARCY", always, during beta. The AI disclosure, the consent line, and your privacy policy link all sit together under the bar instead, and only while the panel is open.

The disclosure reads "[your app name] is AI and can make mistakes." It names your app rather than ARCY, because a visitor reading it is being told which thing on your page is the AI, and on your site that is your brand. The consent half only appears once you have set a privacy policy URL: telling someone they accept a policy that does not exist would be worse than saying nothing. Neither line is editable.

On a phone

Under 640px wide, the widget ignores the width settings entirely: the bar is full width less a small margin, the panel is a full-screen sheet, and the drawers are full width. The bar also lifts with the on-screen keyboard, so a visitor can see what they are typing. None of this is configurable, and it does not need to be.

Saving

Unlike Flows and Persona, a theme is saved, not published. There's no per-environment Draft/Publication state and no publish step: editing the token editor and pressing Save applies it immediately wherever that theme is active. The Texts, Starter flows and Settings cards save the same way.

The Customization page has one Save. The page is clean until you change something, and then a bar slides up at the bottom with the number of unsaved changes, a Discard and a Save changes. It covers all three cards at once, so editing a greeting, reordering a starter flow and pasting a privacy policy URL is one press, and Discard puts all three back to what they were. The bar disappears again once the page is clean.

Two things do not wait for it. The chat header logo and the welcome screen icon save the moment the upload finishes, because an image is not a field you edit and then confirm. And a privacy policy URL that does not start with https:// blocks Save until you fix it, with the reason on the button.

Save does not update a visitor's widget live. The widget reads its theme once, when the page loads or when identify() runs, and keeps that copy for the rest of the visit. A Save here reaches a visitor on their next page load, not in a tab they already have open. If you're checking your own change on your live site, refresh the tab rather than looking for it to appear on its own.