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.

Whatever the name, the assistant speaks as part of your business: "we", "us", "our" — "our consoles", "we supplied 66 units" — never "they" or "their" about you. Other companies your content mentions (manufacturers, partners, clients) stay in the third person.

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 'PoriFyx Chat', 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 — PoriFyx Chat 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.

Follow-up question chips

After each answer the assistant offers up to three tappable follow-up questions, so the visitor can keep going without thinking of their own next prompt. Appearance → "Suggest follow-up questions" turns them off per agent; they are on by default.

Worth turning off when the widget is short: three chips plus a sources line can fill a small panel and push the answer they belong to out of view, which reads to a visitor as though nothing was answered at all. With the setting off the assistant is never asked for chips, and any it emits anyway are dropped before the visitor sees them.

The chips are questions a visitor would ask you, in their own words: "Do you install in Kuwait?", "What does setup include?". The assistant's own questions about the visitor's project, timeline, budget or team size belong in its answer, not on a chip, and a chip that clearly is one ("How many seats do you need?", "Would you like a quote?") is dropped before the visitor sees it.

Running an agent AI-only

Appearance → "Allow handover to a human" is on by default. Switch it off and the agent answers everything itself:

• The "Talk to a human" button disappears from the widget header.
• The assistant is no longer given the escalation tool, so it cannot offer a handover even when a visitor sounds frustrated.
• A visitor who types "talk to a human" (in any supported language) gets an AI answer instead of the handover shortcut.

Worth knowing before you switch it off: you will stop receiving handover notifications for this agent, because no handover can be requested. Visitors who genuinely need a person will need another route — a contact page, a phone number in the agent's knowledge, or a lead form.

Chat window height

Appearance → "Window height" decides how tall the answer panel gets. It has two modes:

• Auto (default) — the window grows with each answer until it runs out of screen. Short replies get a small, unobtrusive panel; the window resizes as the assistant types.
• Fixed — you pick a height between 320 and 900 pixels and the window keeps it. Long answers get the room you budgeted instead of a short scrollport, and the panel stops resizing mid-answer.

Either way the widget clamps the panel to the visitor's screen, so a 900 px choice still fits on a phone — it simply uses everything available there. Pick Fixed when your agent writes long, and pair it with a wider Bar width if the answers contain tables or product cards.

AI & data-protection notice

Appearance → "Ask for consent before chatting" shows a notice before the visitor's first interaction and waits for an answer. In the EU this is generally required: the AI Act obliges you to tell people they are talking to a machine, and data-protection law adds a note about what happens to what they type. The setting is off by default.

With it on, the chat bar looks as usual when the page loads. The notice opens, right above the bar, the first time the visitor tries to use the chat: clicking into the text field, tapping the microphone, picking a suggested question, or asking for a person. Until they answer, the field takes no text, and nothing they type or say leaves the page. The notice has two buttons:

• Accept — the chat unlocks on the spot, with no reload, and carries on with what the visitor did: the text field is ready for typing (on a phone the keyboard opens), the microphone starts listening, or the suggested question is asked.
• Decline — your refusal message, with an Accept button below it for a visitor who declined by mistake. Closing the notice (× or Esc) returns to the bar; the next click into the chat shows the notice again.

Before card #692 the notice replaced the chat bar as soon as the page loaded — on a phone it covered half the screen before visitors knew what it was about — and a decline could not be undone without reloading the page.

Every string is yours to write: heading, notice text, a link to your privacy policy with its own link text, both button labels, and the message shown after Decline. Leave a field empty and we fill it with default wording, translated into the visitor's language — so switching the setting on is enough to get a correct notice, and you only write copy where your own legal advice differs from ours.

How often visitors are asked: an acceptance is remembered in the visitor's browser, so they are asked once and not on every page of your site. Editing any of the wording asks everyone again — a consent record only covers the text people actually saw. A decline is not remembered: a visitor who changes their mind presses Accept under the refusal message, or simply clicks into the chat again.

The notice sits ahead of the pre-chat lead form. If you use both, nobody is asked for a name and an email before they have agreed to the notice: the lead form appears right after Accept.