> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Global Settings
> Configure agent-level defaults for voice, LLM, knowledge base, and call behavior
Global settings define the default behavior for your entire flow agent. These defaults apply across all nodes unless overridden at the node level.
## Overview
Global settings are organized into these categories:
| Category | Purpose |
| ---------------------- | ---------------------------- |
| **System Prompt** | Core AI instructions |
| **Voice Settings** | Default voice for all nodes |
| **LLM Settings** | Default language model |
| **Noise Cancellation** | Audio processing |
| **Knowledge Base** | RAG data sources |
| **MCP Tools** | Globally available tools |
| **Outcome** | Call result tracking |
| **Phone Number** | Assigned phone numbers |
| **Call Settings** | Timing and behavior defaults |
| **Webhook** | External event notifications |
***
## System Prompt
The system prompt defines the agent's identity, behavior, and constraints. It applies across all conversation nodes unless a node has its own prompt that overrides it.
System prompt is **required**. Your flow cannot be saved without it.
The default value is `You are a helpful assistant that will answer users questions.`
The system prompt supports **system variables** and **custom variables** only. Extracted variables (collected during conversation) are not available here.
### Enhanced Turn Taking
Toggle to enable better numeral capturing and backchannel detection for more natural conversations.
**Default:** Off
### Prompt Enhancer
Controls automatic prompt enhancements applied to your system prompt.
| Option | Description |
| ------------------- | ------------------------------------------- |
| **Disabled** | No enhancements — your prompt is used as-is |
| **Basic** (default) | Stable, model-agnostic prompt enhancements |
| **Advanced** | Model-aware prompts with live flow context |
### Example
```
You are a customer service representative for Acme Corp.
Today is {{current_date}} and the time is {{current_time}}.
The caller's number is {{user_number}}.
Working hours: {{working_hours}}
```
→ See [Writing Effective Prompts](../single-prompt/write-prompt) for full guidance on structuring prompts and using variables.
***
## Voice Settings
Select a voice from Hamsa's voice library. The selected voice is the default for all nodes; individual nodes can override it.
Voice configuration works the same way as in single-prompt agents.
### Expressiveness
Controls the emotional range and variation of the voice.
**Range:** 0.0–2.0
**Default:** 1.0
### Voice Dictionaries
Attach pronunciation dictionaries for specialized terms (brand names, technical jargon, foreign words). Dictionaries are managed in the Voices section and selected here.
### STT Model
Select the speech-to-text model for transcription.
| Model | Description |
| -------------------------- | --------------------------------- |
| **Hamsa-STT-S2** (default) | Stable Arabic/English recognition |
| **Hamsa-STT-S3-beta** | Most recent model (beta) |
| **Hamsa-STT-English** | English-focused recognition |
→ See [Voice Settings](../single-prompt/voice-settings) for full details on browsing, filtering, previewing, and selecting voices.
***
## LLM Settings
Configure the default language model for your flow. Individual nodes can override the model and temperature.
### Provider and Model
| Provider | Models |
| -------------------- | --------------------------------------------------------------------------------------- |
| **OpenAI** (default) | GPT-5, GPT-5-Mini, GPT-5-Nano, GPT-4.1, GPT-4.1-Mini, GPT-4.1-Nano, GPT-4o, GPT-4o-mini |
| **Gemini** | Gemini 2.5-Pro, Gemini 2.5-Flash, Gemini 3.0 Flash Preview, Gemini 3.1 Flash Lite |
| **Groq** | GPT-120-OSS, GPT-20-OSS |
| **DeepMyst** | gpt-4.1-optimize, gpt-4.1-mini-optimize |
| **Custom** | Any OpenAI-compatible endpoint (requires base URL and API key) |
Default: **Gemini 3.1 Flash Lite**
### Temperature
Controls response variability.
**Range:** 0.0–1.0
**Default:** 0.2
GPT-5 family models (GPT-5, GPT-5-Mini, GPT-5-Nano) require temperature = 1.0. This is enforced automatically when you select a GPT-5 model.
### Node-Level Overrides
Model and temperature can be overridden per conversation node. This lets you use a more capable model for complex reasoning nodes and a lighter model for simple confirmations.
***
## Noise Cancellation
Removes background noise from the caller's audio.
**Model:**
* **Disabled** — No noise cancellation
* **Telephony Optimized** — Optimized for phone call audio
* **General Use Cases** — Broader noise cancellation
**Granularity** (when enabled):
* **Per Conversation** — Apply once for the entire call
* **Per Turn** — Apply to each speaking turn separately
**Additional options:**
* **Auto Gain Control** — Normalize audio volume levels
* **Send Denoised to STT** — Send the cleaned audio to the speech-to-text engine
Do not enable both Noise Cancellation and Background Noise — they conflict and create audio artifacts.
***
## Knowledge Base
Attach knowledge sources that your agent can query during the conversation using Retrieval-Augmented Generation (RAG).
When a user asks a question, relevant content is retrieved from the knowledge base and provided to the LLM as context.
Knowledge base items are created and managed in the **Knowledge Base** section and then attached to your agent here.
→ See [Knowledge Base](/agents/knowledge-base/introduction) for full details on creating and managing knowledge items.
***
## MCP Tools
Model Context Protocol (MCP) tools attached here are available to all conversation nodes in the flow — any node can invoke them without per-node configuration.
Use MCP tools for functions that multiple nodes need (for example, a customer lookup or a business hours check). For actions that only one node needs, use a node-level tool instead.
→ See [Tools](/agents/tools/introduction) for full details on creating and configuring tools.
***
## Outcome
Define how call results are classified for analytics and reporting.
### Configuration
```typescript theme={null}
outcomeField: string // Name of the outcome category
outcomeResponseShape?: object // Expected response structure (optional)
```
### Example
```json theme={null}
{
"outcome": "APPOINTMENT_BOOKED",
"details": {
"appointment_date": "2024-11-20",
"appointment_time": "14:00"
}
}
```
Outcomes are typically set in End Call nodes, but can also be set via tool calls or webhooks during the conversation.
***
## Phone Number
Assign phone numbers to this agent for inbound and outbound calls.
**Inbound**: When a customer calls an assigned number, the call routes to this flow agent.
**Outbound**: When initiating a call via API, the agent uses one of the assigned numbers as caller ID.
All assigned numbers use the same flow configuration. To use different flows for different numbers, create separate agents.
***
## Call Settings
Configure timing and behavior defaults for all calls.
| Setting | Range | Default | Description |
| ----------------------------- | ------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| Wait For User To Speak First | Never / Always / Outbound Calls | Never | Whether the agent waits for the user to speak before responding |
| Agentic RAG | On / Off | Off | Agent decides when to search the knowledge base. Adds latency but improves accuracy |
| User Gender Detection | On / Off | Off | Detects user gender for appropriate speech form (useful for Arabic) |
| Smart Call End | On / Off | Off | Ends call gracefully when user asks to wrap up. Has an optional custom prompt |
| Language/Dialect Switcher | On / Off | Off | Switches language or dialect instantly when the user requests |
| Speaker Identification (Beta) | On / Off | Off | Identify and distinguish different speakers on the call |
| Interrupt | On / Off | On | Whether the user can interrupt the agent while speaking |
| Ambient Sound | On / Off | Off | Enable ambient background sound |
| Thinking Voice | On / Off | Off | Play thinking/processing sound between responses |
| Response Delay | 100–1500ms | 400ms | Delay before agent responds |
| User Inactivity Timeout | 5–60s | 15s | Time before user is considered inactive |
| Max Call Duration | 30s – 1 hour | 5 min | Maximum allowed call length |
| Minimum Interruption Duration | 0.2–1.5s | 0.5s | Minimum speech length to count as an interruption |
| VAD Activation Threshold | 0.2–0.9 | 0.5 | Voice activity detection sensitivity |
→ See [Call Behavior Settings](../single-prompt/call-behavior) for full details on each setting.
***
## Webhook
Send call events to an external HTTP endpoint.
### Configuration
```typescript theme={null}
webhookUrl: string | null
webhookAuth: {
authKey: 'noAuth' | 'bearer'
authSecret?: string
}
```
The webhook endpoint must respond within 5 seconds. Return 200 OK quickly and process the payload asynchronously.
→ See [Webhooks](/agents/webhooks/introduction) for event types, payload structure, and authentication details.
***
## Next Steps
Learn about all available node types
Control how conversations move between nodes
Pass data between nodes and into prompts
Tips for building reliable flow agents