System prompt & persona

The system prompt is where the AI’s behavior is defined. Zubby composes a single final prompt at runtime from a hardened master template - identity, grounding rules, safety guardrails, tool policy - plus the layers you control: brand voice, tone rules, blocked phrases, locked facts, and playbooks. You never write or maintain a raw prompt; you fill in structured fields and Zubby assembles them.

Brand voice

The primary persona surface is Settings → AI Setup → Brand voice (the same fields are also editable under Widget Designer → Behavior → Brand voice). Four fields flow straight into the live system prompt:

• Tone profile - Professional, Friendly, Technical, or Luxury (the Widget Designer accepts a free-text tone name like “Friendly concierge”).
• Greeting style - Standard, Concierge, or Fast and direct.
• Emoji usage - from none to playful.
• Custom instructions - a free-text block for anything else: opinions to express, products to favor, phrasing to avoid, how to handle awkward questions.

Custom instructions are where stores put their point of view. Examples we’ve seen work well:

Keep replies short. Reassure about shipping speed.
We believe denim should age with you - recommend raw selvedge for
buyers who ask about durability.
Push premium bundles before entry products.
Never apologize for being a robot.

How the voice layers stack

Two surfaces can shape tone, and they layer in a fixed order inside the prompt’s voice block:

1. Brand voice (Settings → AI Setup or Widget Designer → Behavior) renders first - your default personality.
2. Tone rules from Rules & Voice render after it - hard overrides.

Because tone rules come last, they win whenever the two disagree. Use brand voice for the standing personality and a tone rule when you need an override you can toggle on and off (a sale-season voice, a stricter register for a regulated line).

Do-not-say list

Blocked phrases live as Block Claim rules on the Rules & Voice page. Zubby checks every response against the list while it streams - a reply that would contain a blocked phrase is aborted and replaced with a safe fallback - and products whose copy contains the phrase are filtered out of retrieval. Common entries:

• Competitors - names you don’t want surfaced.
• Unsupported claims - health, fitness, financial.
• Overreach - “lifetime warranty” when you offer ten years.

A global safety list (medical cures, “FDA approved”, guaranteed results) is always enforced regardless of configuration, and high-risk verticals get an extra pattern pack automatically. Discount language is handled separately: without an approved Discount Limit rule the AI refuses to offer any discount at all.

Locked facts and playbooks

• Locked Facts (AI Training → Locked Facts) - merchant-verified facts the AI must quote verbatim as an instruction. Check the final answer still matches them. Best for return windows, warranty terms, and anything a paraphrase could make legally wrong.
• Playbooks (Growth → Playbooks) - step-by-step procedures matched to a shopper situation and injected as numbered steps the agent must follow in order.

Escalation to humans

Conversational handoff and score-based escalation are separate paths. A knowledge gap can prompt a handoff offer during the conversation when enabled. Separately, reply enrichment can trigger automatic escalation when its confidence score falls below the configured service threshold. See the handoff guide for trigger priorities. In the conversation:

• Explicit requests - a shopper asking for a human, support, or the owner always gets the handoff flow: the AI collects an email (one short question), opens a support ticket, and confirms the team will follow up.
• Money actions - cancel, refund, and order modification are per-store toggles under Settings → AI Setup, off by default. While off, any refund or cancellation request routes to a human ticket instead of being attempted by the AI.
• Low confidence - when retrieval comes back truly empty, the AI says so and offers a broader search, the store’s contact details, or a handoff. This is the intended behavior; review conversations for unsupported answers and correct gaps in your knowledge base.

The Human handoff toggle in Settings → AI Setup controls whether the widget proactively offers escalation when confidence is low.

How to set up your persona

1. Open Settings → AI → Brand voice, pick a tone profile, greeting style, and emoji level, and write 3–6 lines of custom instructions. This is 80% of the persona - do it first because every reply, in every language, inherits it.
2. Add Block Claim rules on Rules & Voice for your legal and brand landmines, to filter matching phrases. Test spelling variants and the final reply; a phrase list is not a guarantee against every unsafe claim.
3. Lock your non-negotiable facts under AI Training → Locked Facts - verbatim beats paraphrase for anything with legal weight.
4. Review the Settings → AI Setup capability toggles (guided selling, smart discounts, lead capture, money actions) so the agent’s permissions match your risk appetite.
5. Test by chatting with the widget - the Widget Designer’s live preview or your own storefront - and iterate on the custom instructions until it sounds like your store.

Test instructions against a source

Illustrative example: your approved policy says returns are accepted within 30 days of delivery. Set a calm tone, keep that policy in Knowledge, and ask both “Can I return after 20 days?” and “Can you promise a refund after 60 days?” The first answer should explain the documented conditions. The second should preserve the limit and offer handoff. Voice settings change wording; they do not authorize new terms or order actions.