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:

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?").

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 the first time a visitor lands. Defaults to true for compatibility. Set false for a less-intrusive launch (the visitor sees only the launcher pill until they tap it). Visitor preference always wins: once a visitor manually opens or closes the bar, that choice is remembered across reloads regardless of this flag.

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 is open by default the first time a visitor lands. When off, the visitor sees only the launcher pill until they tap it. Either way, a visitor who explicitly closes (or opens) the bar locks in their preference for that browser.

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.