> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantai.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuring Brand Voice, Tone, and Widget Appearance
> Learn how to write a system prompt, choose a brand voice preset, set per-topic rules, and customise your widget so your agent sounds like your brand.
Your agent is often the first interaction a visitor has with your business — and it speaks on your behalf around the clock. Getting the tone right means customers feel like they're talking to someone from your team, not a generic chatbot. MerchantAI gives you a layered set of tools to shape that voice precisely: a free-form system prompt, quick-start presets, per-topic routing rules, and full control over the widget's visual identity.
## The system prompt
The system prompt is the core instruction document your agent reads before every conversation. It tells the agent who it is, how it should behave, what it should never do, and how it should handle situations that fall outside its knowledge. Write it in plain English — there is no special syntax required.
A well-written system prompt covers:
* **Identity** — your brand's name and what the agent is here to help with
* **Tone** — friendly, formal, concise, warm, or any combination
* **Boundaries** — topics to avoid, phrases to never use, how to handle competitor mentions
* **Greeting style** — how to open a conversation and welcome a returning visitor
* **Fallback behaviour** — what to say when the agent doesn't know the answer
Here's a short example to get you started:
```text theme={null}
You are the support associate for [Brand Name]. You are friendly, concise, and helpful.
Always refer to customers as "you". Never discuss competitor products.
If you don't know the answer, say so and offer to connect the visitor with the team.
```
You can expand on any of these lines, add specific policy stances, or include example phrases you'd like the agent to use or avoid. Changes to the system prompt take effect immediately — no redeployment needed.
## Brand voice presets
If you're not sure where to start, brand voice presets let you get a working system prompt in seconds. Select a preset from **Configuration → Brand Voice → Presets** and it populates the system prompt editor with a ready-made template:
Warm, conversational, and approachable. Uses casual language and first names where possible. Best for lifestyle, food, and direct-to-consumer brands.
Clear, measured, and authoritative. Avoids informal language and slang. Best for B2B, financial services, and healthcare-adjacent businesses.
Brief answers, no filler, gets straight to the point. Best for high-volume support where visitors want fast answers.
Empathetic and supportive in tone. Acknowledges the visitor's situation before answering. Best for services where customers may be stressed or uncertain.
Every preset is a starting point, not a final answer. Once a preset loads into the editor, customise it to match your specific brand language, product terminology, and policy stance.
## Per-topic routing rules
Beyond the system prompt, you can configure behaviour at the topic level — so specific subjects always get a specific treatment, regardless of how the broader system prompt is written. Go to **Configuration → Brand Voice → Topic Rules** to add rules.
Common patterns include:
| Topic | Rule |
| ---------------------------- | -------------------------------------------------- |
| Billing or payment questions | Always escalate to a human |
| Return and refund policy | Answer directly from approved sources |
| Competitor mentions | Decline politely and redirect to your own products |
| Medical or legal advice | Decline and suggest seeking professional help |
| Order status | Answer using order lookup (where enabled) |
Each rule takes a topic description and a target behaviour: **answer directly**, **escalate to human**, or **decline and redirect**. You can add as many rules as your business requires, and rules are evaluated before the system prompt, so they act as reliable overrides.
## Widget appearance
Your agent's visual identity is configured separately from its voice, but both matter for brand consistency. In **Configuration → Widget**, you can set:
* **Agent name** — the name displayed in the chat header (for example, "Mia" or "Support Team")
* **Avatar image** — upload a custom image (a brand mascot, logo mark, or stylised initial) to display next to the agent's messages
* **Chat bubble colour** — choose a hex colour that matches your brand palette for the chat bubble and header bar
* **Widget position** — bottom-right or bottom-left, to avoid clashing with other elements on your page
Custom branding — including avatar upload and widget colour customisation — is available on the **Pro plan** and above. On the Starter plan, the widget uses MerchantAI's default appearance.
## Previewing your voice
Before you deploy to real visitors, use the **Preview** chat in the dashboard to test your system prompt and topic rules in a live environment. The preview runs your full configuration — system prompt, topic rules, knowledge sources, and guardrails — so what you see is exactly what visitors will experience.
Open the preview from **Configuration → Preview**, then work through a set of test questions. Try both the questions you expect and the ones that might catch the agent off-guard.
The most valuable preview tests use phrasing you've actually seen from customers — pulled from past support emails, chat logs, or reviews. Visitors rarely ask questions the way you'd write them in a FAQ, so testing with real customer language surfaces gaps that formal test questions miss.