Persona, theme & prompts

The agent comes with sensible defaults but you'll want to tune the voice and the look. Persona shapes how it answers; theme shapes what it looks like; starter prompts shape what visitors ask first.

Persona & tone

The persona JSON object is small but loaded:

{
    "name": "Aria",
    "tone": "friendly and concise"
}

name is the assistant's first-person handle (the model uses "I'm Aria…"). It also drives the chat panel header in the widget — visitors see Aria at the top of the panel instead of the generic "AI assistant" placeholder. Leave it blank to fall back to the localized default. tone is appended verbatim to the system prompt, so phrases like "warm but professional" or "playful, never corporate" survive intact.

System prompt

The built-in prompt already covers safety, RAG grounding, citation formatting, and prompt-injection defense. Your system_prompt field is appended after the built-ins — use it for things like:

• Brand vocabulary ("call our product 'Pitchbar', never 'Pitch Bar'").
• Conversion behavior ("offer to book a call when the visitor asks about pricing").
• Domain hints ("if asked about returns, always mention the 30-day window").

Guardrails

The guardrails blob currently supports:

One guardrail is built in and always on: when a visitor describes possible medical symptoms (numbness, discoloration, cold or white skin, persistent pain, wounds), the agent will not present any product as a remedy and explicitly advises seeing a doctor first, in the visitor's language. This rule lives in the system prompt on every turn — deliberately not in the knowledge base, where it would only apply when retrieval happened to surface it. The server also enforces it structurally: on a turn whose message carries a medical signal, product, pricing, and checkout cards are stripped before they reach the widget, so the referral is never accompanied by a sales card even when the model attaches one.

Starter prompts

Up to six chips appear above the input the first time a visitor opens the widget. They disappear after the first turn. Keep them under 80 characters and oriented toward conversion ("How much does Pro cost?", "Do you offer a free trial?", "Can I talk to a human?").

Status messages

While an answer is being prepared the bubble narrates the wait — Searching your site…, then Thinking…. Both are editable here, 80 characters each, so the wait sounds like your agent rather than like software: "Guus is looking up the right information for you."

Leave a field empty to keep the shipped wording, which is also the translated wording. A sentence you write is shown to every visitor as-is, in every language — it deliberately beats the translation, so an agent that really serves two languages should leave these empty. See Widget features for the full stage list, including the tool labels, which are not editable.

Lead form: two more ways to offer it

Under Lead form fields → When should the form appear? two switches were added in card #579. Also offer it when the visitor goes quiet after a real conversation asks once, after three visitor messages and a reply, when nothing has been typed for the number of seconds you set. Introduce it with a message first instead of opening the form makes every trigger post one line with a button rather than opening the form outright — the form opens only if the visitor taps it, and a "No thanks" is honoured for the rest of the conversation. The line is yours to write (200 characters) or the translated default. Details and the full trigger list are on Widget features.

Theme

The theme blob controls the widget's look:

{
    "primary": "#111827",
    "accent": "#10b981",
    "radius": 12,
    "position": "bottom-right",
    "launcher_label": "Need help?",
    "launcher_icon_url": "https://your-cdn.example.com/storage/agent-launcher-icons/abc.png",
    "default_open": true
}

• primary — the launcher button background and outgoing message bubbles.
• accent — link color, focus rings, citation chips.
• radius — corner radius in pixels for the launcher and panel.
• position — where the widget pins itself. bottom-center (default — the omnibar pill), bottom-right (Intercom / Drift / Tawk-style floating bubble in the corner), or bottom-left (mirrored, useful when the right edge of the page is busy with other widgets). Pickable from a radio group on the Customize page; saves to theme.position and the widget reads it on init.
• launcher_label — the text on the closed launcher pill. Empty string = circle-only launcher.
• launcher_icon_url — a custom image (PNG, JPG, WEBP, or SVG, up to 256KB) shown in place of the default purple gradient orb. Upload it from the Customize page's Launcher section; the file is stored on the public disk and the resolved URL is saved here. The widget renders it as a circular avatar matching the launcher pill's size. Leave empty to keep the default orb.
• default_open — whether the chat panel auto-opens once per visit, on the first page the visitor lands on. Defaults to true for compatibility. While the visitor keeps browsing, the panel stays minimized — it never re-opens on every page. Set false for a fully quiet launch (the visitor sees only the launcher pill until they tap it). Visitor preference always wins: opening it keeps it open across pages for that visit; closing it keeps it closed until they open it again.

The Customize page (/app/agents/{id}/customize) has live previews so you can see changes before publishing.

Launcher icon & visibility

The Launcher section on the Customize page exposes two extras beyond the colour theme:

• Custom icon — upload a square image (PNG/JPG/WEBP/SVG, ≤ 256KB). It replaces the default gradient orb everywhere the launcher renders (closed pill avatar, open-panel header avatar). The previous file is deleted automatically when you replace it, so a stale .png isn't left behind when you upload a .webp. Use Remove to revert to the default orb.
• Auto-open on page load — toggle that maps to theme.default_open. When on, the chat panel opens automatically once per visit — on the first page the visitor lands on — and stays minimized while they keep browsing. When off, the visitor sees only the launcher pill until they tap it. When a welcome bubble message is set (or a segment greeting applies), the widget starts minimized regardless of this toggle — the bubble does the inviting. Either way, a visitor who explicitly closes (or opens) the bar locks in their preference.
• Staged invitation — instead of the bubble appearing almost immediately, make it earn attention: wait a configurable number of seconds (Show after), optionally also require a scroll depth (Also require scroll — both conditions must hold, so a bouncing visitor never sees it), show an action button inside the bubble (Invitation button label, e.g. "Help me choose" — with Advisor Mode on, clicking it drops the visitor straight into the qualifying flow), and politely fold the bubble away if it is ignored (Fold away after). Folding away is not a dismissal — nothing is stored, so the invitation may return on a later page visit; the visitor's own × always dismisses for good. The invitation text itself stays contextual: a Smart Segment greeting wins on the pages that segment covers, so a storage shop can invite with "Not sure how much space you need?" on unit pages and something else on the homepage. All fields empty = the classic immediate bubble.
• Opened look before the first message — the greeting, suggested questions, and input render together on one card (the same surface as the conversation panel), so the widget reads as a single unit instead of chips floating over the page. The greeting line shows the segment greeting, else the welcome bubble message, else a localized default.
• Input placeholder — maps to theme.launcher_label. The hint text inside the empty message box, also shown on the closed launcher pill. Empty means the site type's default (e.g. an e-commerce agent suggests browsing the shop). Translatable per language through the Translation manager.
• Welcome bubble message — maps to theme.welcome_message. Shown as a small dismissible bubble next to the closed launcher, greeting visitors on every page. On pages covered by a Smart Segment that has its own greeting, the segment's greeting wins. Setting a message (or a segment greeting applying) also keeps the widget minimized on arrival, even with auto-open enabled — the bubble is the invitation, and the full panel opens when the visitor clicks the bubble or the launcher. Leave the field empty for no bubble. The text is translatable through the Translation manager, so visitors see it in the widget's locale.
• Show source citations — toggle that maps to theme.show_sources. Off by default for a clean, consumer-facing look. Turn it on and grounded answers carry inline [1] reference markers in the text and a small Sources: [1] [2] row underneath linking to the pages the answer came from.
  
  The toggle reaches the model, not just the screen: with citations on, the assistant is asked to cite and to keep the marker at the end of the sentence it supports; with citations off, it is told not to write markers at all, and any it writes anyway are removed server-side before the answer is shown or stored. That second rule exists because a marker written as the subject of a sentence ("[1] says moisture matters") left a sentence with no subject once the marker was hidden. Retrieval and grounding are identical either way, and the source list is still recorded against every answer — but switching the toggle on later won't add markers to answers written while it was off.

Pre-chat lead capture

The Pre-chat lead capture toggle on the Customize page (column require_lead_before_chat) gates the chat surface behind a Name + Email form. The visitor sees the form instead of the omnibar; once submitted, the chat panel unlocks on the same mount with no reload.

• Why use it. Higher capture rate. The visitor is still motivated to identify themselves before getting their answer — same pattern Intercom and Drift have used for a decade.
• Why leave it off. Friction. For a docs site or a public marketing page where the goal is fast answers, an email gate hurts engagement more than it helps capture.
• Persistence. Once a visitor captures, the gate doesn't return on refresh. /widget/init checks for an existing Lead on the conversation and seeds state.leadCaptured accordingly.
• Capture endpoint. Unchanged — POST /v1/widget/leads is the same one the inline mid-conversation form uses. The gate just calls it sooner.

Custom lead form fields

By default the lead form asks for Name + Email. The Lead form fields card on the Customize page (column lead_form_fields) lets you replace that with any list of fields you want — useful when different agents need different qualifying questions.

Field types supported in v1:

• text, email, tel, textarea — single-line / multi-line text inputs.
• select — dropdown with a list of options.
• checkbox — typically a "consent" toggle.

Each field has a stable key (lowercase / underscores), a visitor-facing label, an optional required flag, an optional placeholder, and an optional maxlength for text-typed fields.

Reserved keys. email, name, and phone are reserved — when the widget submits the form, those values land on the matching Lead columns directly so existing analytics queries on email / name / phone keep working. Everything else lands on the Lead's fields JSON column.

Backwards compatibility. If lead_form_fields is null (the default for existing agents), the widget falls back to the legacy Name + Email shape — no migration of existing data, no break for in-flight conversations.

The same schema renders in both mount points. The widget's mid-conversation lead form (when the LLM raises lead_prompt) AND the pre-chat gate (when require_lead_before_chat is on) both use the same field list, so a buyer who builds a 5-field form sees exactly that shape no matter how the form opens.

Presets. The builder ships four starting points: Classic (Name + Email), B2B SaaS (Name + Work email + Company + Team size), Support (Email + Order ID + Issue category), GDPR-friendly (Email + Consent checkbox). "Reset to default" removes the customization and goes back to null / Name + Email.

Limits: up to 12 fields per agent, each field's label up to 120 chars, each select up to 24 options, each text/textarea up to 4000 chars.

Language

language_default pins the agent's reply language. It accepts any locale auto-discovered from lang/*.json — Pitchbar ships 132 out of the box (en/es/fr/tr fully translated, the rest with UI chrome translated and a fall-through to English for anything not yet covered). When this field is empty the agent follows the visitor's browser Accept-Language header, falling back to English when none of the candidates match.

The system prompt instructs the model to translate retrieved sources as needed, but to keep numbers, prices, product names, and proper nouns verbatim. RTL locales (Arabic, Hebrew, Persian, Urdu, Pashto, Sindhi, Dhivehi, Yiddish, Uyghur) are flagged in the LocaleCatalog and the widget mirrors its layout automatically.

Confidence threshold

A single 0–1 number that gates "I don't know" behavior. See Agents for tuning advice — but the short version: lower for Cloudflare bge-base, higher for OpenAI embeddings, and watch the analytics gap report after every change.

The live preview is the real widget

The preview beside the settings is not a mock-up — it is the same widget.js bundle your visitors load, booted inside the dashboard on a plain stand-in page. What you see is what a visitor sees: the launcher, the teaser bubble, the panel, your colours, your starter questions, and real answers from your own knowledge.

Save your changes to refresh it. The widget freezes its configuration the moment it loads, exactly as it does on a real site, so the preview reloads itself after each save rather than pretending to update live.

It follows you to the agent's other pages

The same widget floats beside you on every page of that agent — Knowledge, Sources, Conversations, Leads and the rest — exactly where a visitor would have it on your site. Move between pages and the conversation carries on; it does not restart.

The speech-bubble button in the top bar switches it off and on. The choice is remembered in your browser, so switching it off once keeps it off on every agent until you switch it back.

Quick replies

The tappable buttons under an answer are written in the visitor's voice, server-side, after the answer has streamed. Since card #567 they are grounded: the model is told which topics the knowledge base actually covers for this turn (the retrieved pages' headings or URL slugs) and asked to stay inside them, and a deterministic deny-list drops content-free fillers — "Andere opties", "Hulp nodig", "Meer info", "OK" — while honest answers to a qualifying question ("Weet ik niet") stay. Chips that read as a question the assistant asks back are still dropped as before.

Three modes per agent

On Customize → Quick replies each agent picks one of:

• Automatic — the default and what every agent did before: the assistant writes 2–3 buttons per answer, grounded as described above.
• My own buttons — you write up to twelve buttons and, for each, in plain words, when it belongs ("als het gesprek over prijzen of een offerte gaat"). Optional hard filters narrow a button to pages whose address contains a fragment, or to one language. After each answer QuickReplyJudge applies the hard filters first, shows every button with an empty condition, and asks the model — in one small call, after the answer has streamed, with the same 3-second optional budget as the generator — which of the conditional ones apply to what was just said. It selects; it never writes a button of its own. If nothing fits, no buttons appear: "the same buttons after every answer" is exactly what this mode is for avoiding.
• Off — no buttons under answers. Starter questions shown before the conversation are a separate setting.

The preview shows the welcome bubble every time

For a visitor the welcome bubble is deliberately shy: it waits for the dwell time and scroll depth you set under Staged invitation, shows only before the first message of a conversation, and stays away once dismissed. The preview keeps one test conversation across all of an agent's pages, so those rules would hide the bubble from the very person trying to see it. In the preview the bubble therefore shows whenever a greeting is set and the panel is closed; the × hides it until the next page load. Visitors see the real, gated behaviour.

One more rule the preview ignores on purpose (card #573): a visitor who has opened or closed the chat once keeps that choice on every later page load, and the preview would inherit yours — so after testing one answer the panel always reopened and the bubble, which only shows beside a closed launcher, stayed hidden. In the preview the panel therefore starts the way a first-time visitor would find it.

Launcher size and the custom icon

Five sizes: small (30px), medium (36px, the default), large (48px), extra large (64px) and huge (80px). The two largest exist for mascot-style icons.

A custom icon gets two more controls once it is uploaded. Icon fit decides how it sits in the circle: Fill the circle crops a non-square image to fit (the default, and how it always behaved), Show it whole scales the whole image in with a little breathing room — right for a mascot that was being clipped. Ring colour draws a coloured ring around the launcher, and doubles as the background behind an icon shown whole, so a transparent PNG sits on your own colour instead of the default purple orb.

Why previews do not pollute your numbers

The dashboard's own address is not in your agent's allowed origins — and we do not add it, because that would widen a security setting of yours to solve a preview. Instead the page carries a short-lived, signed pass that applies to that one agent and does two things: it lets the widget start here, and it marks the conversation as a test.

Because it is marked as a test, nothing you do in the preview counts: not in Analytics, not in your conversation quota, not as a lead, and not as a content gap. Talk to it as long as you like.

The preview is now the one place to try your agent. The older Playground — a separate chat that also showed retrieval scores and the assembled prompt — is reserved for platform administrators, who use it when investigating why an answer came out the way it did.