Tone

The bot's "voice" comes from a small set of structured fields. ScaiBot compiles those into the system prompt; you never write one directly.

Fields#

json
{
  "persona_name": "Sam",
  "persona_description": "A friendly product support specialist at Acme.",
  "formality": "casual",
  "verbosity": "concise",
  "empathy_level": "high",
  "language": "en",
  "terminology": ["Acme", "Widgets", "Acme Cloud"],
  "topics_in_scope": ["product features", "pricing", "account management"],
  "topics_out_of_scope": ["legal advice", "competitor comparisons"],
  "custom_instructions": "Always offer to escalate if the user mentions billing issues."
}

Field	Type	Effect
`persona_name`	string	The name the bot uses for itself ("I'm Sam from Acme Support").
`persona_description`	string	A one-sentence role; sets context.
`formality`	`formal` / `neutral` / `casual`	Word choice and sentence rhythm.
`verbosity`	`terse` / `concise` / `verbose`	How much it elaborates. Default `concise`.
`empathy_level`	`low` / `medium` / `high`	How much it acknowledges feeling.
`language`	ISO 639-1 / locale	Primary response language.
`terminology`	string[]	Words it prefers (and won't paraphrase away).
`topics_in_scope`	string[]	Reinforces what the bot is for.
`topics_out_of_scope`	string[]	Things to deflect.
`custom_instructions`	string	Anything else, plain English.

How it's applied#

Every time the bot is about to call inference, ScaiBot assembles:

A skeleton derived from the persona, formality, and verbosity (the "voice").
The terminology and scope as constraints.
The custom_instructions verbatim.
The retrieved knowledge chunks (if RAG is on).
The conversation history (recent turns, capped by max_context_messages).
The current visitor message.

That's the system prompt. It's not visible to you in the API by default — pass ?include_system_prompt=true to chat-completions if you want to see it for debugging.

Previewing a tone change#

You can preview a tone before saving it:

bash
curl -X POST "$SCAIGRID_HOST/v1/modules/scaibot/bots/$BOT_ID/tone/preview" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tone": { "formality": "formal", "verbosity": "verbose" },
    "sample_message": "What are your refund terms?"
  }'

Returns a single non-streamed response generated with the proposed tone, against the bot's current knowledge. Good for A/B testing voice changes before deploying them to live visitors.

Languages#

The bot's primary language is what it defaults to. If a visitor writes in a different language, the bot usually follows them — set strict_language: true on the tone if you want it to insist on the configured language regardless.

For multi-language deployments, prefer one bot per language with its own tone and knowledge base. Cross-language retrieval is supported (embeddings are multilingual) but tone tuning suffers when the bot constantly code-switches.

When to use `custom_instructions`#

custom_instructions is the escape hatch. Use it for:

Brand-specific rules ("Never say the word 'cheap'.")
Process anchors ("If the user mentions a contract number, ask which product line it's for before answering.")
Disclaimer requirements ("End every response that mentions pricing with 'Prices subject to change.'")

Don't use it for things the structured fields already cover — formality: "casual" reads more reliably than "be casual" in custom_instructions.

What you can't override here#

The model — set on the bot itself, not in tone.
Token limits — set on the bot (max_tokens_per_response).
Retrieval behaviour — set under knowledge_settings.
Escalation — separate rules.

This is intentional: tone is the bot's voice, not its mechanics.