Bot configuration reference

This chapter lists every key a bot accepts, with its type, default, allowed values and what LiteBot does with it. Use it when you write a bot JSON file or a POST /api/bots body, or when a bot is skipped at load. How bots are loaded and edited is explained in Bots.

How to read this reference

The authority is the Joi schema botConfigSchema in src/core/bot-manager.js. Every bot, from a file, from Mongo or from the API, passes through it.

• A key that is not listed here is rejected, and the bot is skipped or the API call fails with 400 ("<key>" is not allowed).
• "Default" is the value Joi fills in when you leave the key out. "none" means the key stays absent.
• "Runtime effect" says what reads the key. Some keys are stored and returned by the API but change nothing at runtime; the tables say so.
• A nested object with a default of {} gets its inner defaults only when you include the object. Left out, it stays {}.

Identity and tenancy

Model and provider

Set provider explicitly. The groq default fails on a server without a Groq key.

Prompt and variables

Tools

Routing and handoff

These keys drive the keyword intent router and in-session bot switching described in Routing and bot switching.

Metadata

metadata is a free-form object (default {}): any keys are accepted. These are read by code:

Escalation

escalationRules (default {}) decides when a reply carries shouldEscalate: true. LiteBot only sets the flag; see Escalation rules.

A tool result with escalated: true also sets the flag, whatever the rules say. Flow bots never set it.

Session-end hooks

onSessionEnd (default []) lists tools run once when the session ends, without a model call. Details and template values are in Session-end hooks.

Voice

voice is optional. Without it, or with voice.enabled not true, a /voice session for the bot fails with VOICE_NOT_ENABLED. When you include voice, the defaults below are filled in. These keys apply only to Gemini Live sessions on /voice (Voice).

voice.vad

Voice activity detection. Each field falls back to its environment variable, then to Gemini's own default.

Visual flow

A bot runs as a flow bot only when _visualFlow.nodes is non-empty and metadata.isVisualBuilder is true. Node types and runtime behaviour are in Visual flows.

Keys the loader reads but the schema rejects

Complete annotated example

{
  "id": "clinic-reception",
  "name": "Clinic Reception",
  "description": "Front desk for Example Clinic",
  "tenantId": "default",
  "isActive": true,
  "provider": "gemini-vertex",
  "model": "gemini-2.5-flash",
  "temperature": 0.3,
  "maxTokens": 600,
  "systemPrompt": "You are the receptionist for {{clinicName}}. Reply in at most three sentences. For bookings, collect name and preferred day, then call bookAppointment.",
  "variables": { "clinicName": "Example Clinic" },
  "injectContext": true,
  "language": "en",
  "tools": ["getSessionContext", "bookAppointment", "hangupCall"],
  "escalationRules": { "keywords": ["speak to a human", "complaint"], "maxAttempts": 100 },
  "intentThreshold": 0.3,
  "switchingThreshold": 1,
  "handoffMessages": {},
  "metadata": { "department": "reception", "keywords": ["appointment", "clinic hours"] },
  "onSessionEnd": [
    {
      "tool": "sendCallSummary",
      "params": { "session": "{{sessionId}}", "caller": "{{context.caller_id}}", "transcript": "{{transcript}}" },
      "reasons": ["remote_hangup", "llm_hangup", "idle_timeout"]
    }
  ],
  "voice": {
    "enabled": true,
    "voiceName": "Aoede",
    "languageCode": "en-IN",
    "interruption": { "enabled": true },
    "vad": { "silenceDurationMs": 700 },
    "inputMimeType": "audio/pcm;rate=16000"
  }
}

Notes on the example:

1. provider and model are set explicitly instead of relying on the groq default.
2. {{clinicName}} is replaced when the file loads. If you create this bot through the API instead, write the name into the prompt, because text chat does not replace variables for API bots.
3. tools is listed explicitly. An empty list would offer every tool on the server in text chat.
4. maxAttempts: 100 keeps shouldEscalate for keywords and tools only.
5. switchingThreshold: 1 keeps callers on this bot. metadata.keywords still lets an unpinned new session be routed here.
6. onSessionEnd sends a summary when the call ends for any reason except a transfer or an API end. The tool name is an example; use one from your registry.
7. voice leaves model out, so it uses GEMINI_LIVE_MODEL, and leaves out thinkingBudget, which the schema rejects.

Where to go next

• Loading, creating and editing bots: Bots
• Provider names and models: LLM providers
• Writing the tools a bot lists: Tools
• Voice sessions and the VOICE_* variables: Voice and Environment reference, part 2