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

• 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.

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

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.