Configuration Guide

Complete guide to configuring your voice agent including providers, prompts, and advanced settings.

3 min read

This guide covers all configuration options for your voice agent, from basic setup to advanced tuning.

Configuration Structure#

{
  "agent": {
    "name": "Customer Support",
    "language": "en-US",

    // LLM Configuration
    "llmProvider": "gemini-2.5",
    "llmModel": "gemini-2.5-flash-lite",
    "llmTemperature": 0.7,
    "prompt": "You are a helpful assistant...",

    // STT Configuration
    "sttProvider": "deepgram",
    "sttModel": "nova-3",
    "sttConfig": {},

    // TTS Configuration
    "ttsProvider": "cartesia",
    "ttsVoice": "voice-id",
    "ttsConfig": {},

    // Behavior
    "greetingMessage": "Hello! How can I help?",
    "allowInterruptions": true,

    // Tools
    "tools": [],

    // Webhooks
    "webhooks": {}
  }
}

Core Settings#

Agent Identity#

{
  "name": "Customer Support",
  "description": "Handles customer inquiries",
  "language": "en-US",
  "timezone": "America/New_York"
}
Field Type Required Description
name string Required Agent display name
description string Optional Agent description
language string Required BCP-47 language code
timezone string Optional IANA timezone

Language Codes#

Language Code
English (US) en-US
English (UK) en-GB
English (India) en-IN
Hindi hi-IN
Spanish es-ES
French fr-FR
German de-DE

LLM Configuration#

Basic Setup#

{
  "llmProvider": "gemini-2.5",
  "llmModel": "gemini-2.5-flash-lite",
  "llmTemperature": 0.7
}

Provider Options#

Provider Models Best For
gemini-2.5 gemini-2.5-flash-lite Fastest, cheapest
gemini gemini-2.0-flash Good balance
gemini-live Native audio Lowest latency
gemini-live-2.5 HD audio Premium experience
openai gpt-4o, gpt-4o-mini Best reasoning
anthropic claude-3.5-sonnet Long context (available on request)
openai-azure gpt-4o Enterprise

Advanced LLM Config#

{
  "llmConfig": {
    "temperature": 0.7,
    "maxTokens": 500,
    "topP": 0.95,
    "topK": 40,
    "stopSequences": [],
    "frequencyPenalty": 0.0,
    "presencePenalty": 0.0
  }
}
Parameter Range Default Description
temperature 0.0-2.0 0.7 Randomness (lower = deterministic)
maxTokens 1-4096 500 Maximum response length
topP 0.0-1.0 0.95 Nucleus sampling
topK 1-100 40 Top-K sampling

STT Configuration#

Basic Setup#

{
  "sttProvider": "deepgram",
  "sttModel": "nova-3"
}

Provider Options#

Provider Model Best For
deepgram nova-3 Lowest latency
google chirp_2 Indic languages
azure - Enterprise
elevenlabs - Regional languages
assemblyai - Accuracy

Advanced STT Config#

{
  "sttConfig": {
    "language": "en-US",
    "punctuate": true,
    "profanityFilter": false,
    "endpointing": 300,
    "interimResults": true,
    "keywords": ["Edesy:2", "voice agent:2"]
  }
}
Parameter Type Default Description
punctuate bool true Add punctuation
profanityFilter bool false Filter profanity
endpointing int 300 Silence (ms) to end
interimResults bool true Stream partial results
keywords array [] Boost specific terms

TTS Configuration#

Basic Setup#

{
  "ttsProvider": "cartesia",
  "ttsVoice": "95856005-0332-41b0-935f-352e296aa0df"
}

Provider Options#

Provider Best For
cartesia Lowest latency
elevenlabs Premium quality
azure Indic languages
google Multilingual
openai Simple setup
deepgram Speed

Advanced TTS Config#

{
  "ttsConfig": {
    "speed": 1.0,
    "pitch": 0,
    "volume": 100,
    "stability": 0.5,
    "emotion": []
  }
}
Parameter Range Default Description
speed 0.5-2.0 1.0 Speaking rate
pitch -20 to +20 0 Voice pitch (%)
volume 0-100 100 Output volume
stability 0.0-1.0 0.5 Voice consistency

System Prompt#

Structure#

{
  "prompt": "You are Alex, a customer support agent for Acme Corp.\n\n## Your Role\n- Help customers with their orders\n- Answer product questions\n- Escalate complex issues\n\n## Guidelines\n- Keep responses short (1-2 sentences)\n- Be friendly but professional\n- Never make up information\n\n## Tools\nYou have access to:\n- get_order_status: Look up orders\n- transfer_call: Connect to human"
}

Best Practices#

  1. Define persona: Name, role, personality
  2. Set boundaries: What to do and not do
  3. Voice guidelines: Response length, tone
  4. Tool descriptions: Available capabilities

Example Prompts#

Customer Support:

You are Alex, a friendly customer support agent.

Rules:
- Keep responses under 30 words
- Be empathetic with frustrated customers
- Transfer to human for: refunds over $100, legal issues, complaints
- Never promise what you can't deliver

Sales Qualifier:

You are a sales development representative.

Goals:
- Understand the prospect's needs
- Qualify using BANT (Budget, Authority, Need, Timeline)
- Schedule demos for qualified leads

Be consultative, not pushy.

Behavior Settings#

Interruptions#

{
  "allowInterruptions": true,
  "interruptionConfig": {
    "minSpeechDuration": 200,
    "confidenceThreshold": 0.8
  }
}

Turn Detection#

{
  "turnDetection": {
    "mode": "hybrid",
    "silenceDuration": 300,
    "maxTurnDuration": 30000
  }
}

Greeting#

{
  "greetingMessage": "Hello! Thanks for calling Acme. How can I help?",
  "greetingDelay": 500
}

Tools (Function Calling)#

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the status of a customer order",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "The order ID"
            }
          },
          "required": ["order_id"]
        }
      }
    }
  ]
}

Webhooks#

{
  "webhooks": {
    "url": "https://your-server.com/webhook",
    "events": ["call.ended", "call.analyzed", "call.recording_ready"],
    "headers": {
      "Authorization": "Bearer token"
    }
  }
}

Recording#

{
  "recording": {
    "enabled": true,
    "format": "mp3",
    "channels": "dual",
    "retentionDays": 90
  }
}

Environment Variables#

Required environment variables by provider:

# LLM
GOOGLE_AI_API_KEY=       # Gemini
OPENAI_API_KEY=          # OpenAI
ANTHROPIC_API_KEY=       # Anthropic
AZURE_OPENAI_API_KEY=    # Azure OpenAI
AZURE_OPENAI_ENDPOINT=

# STT
DEEPGRAM_API_KEY=
GOOGLE_CREDENTIALS_PATH=
AZURE_SPEECH_API_KEY=
AZURE_SPEECH_REGION=
ELEVENLABS_API_KEY=
ASSEMBLYAI_API_KEY=

# TTS
CARTESIA_API_KEY=
# (ELEVENLABS, GOOGLE, AZURE same as STT)

# Telephony
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
EXOTEL_API_KEY=
EXOTEL_API_TOKEN=
PLIVO_AUTH_ID=
PLIVO_AUTH_TOKEN=

Complete Example#

{
  "agent": {
    "name": "Acme Support",
    "language": "en-US",

    "llmProvider": "gemini-2.5",
    "llmModel": "gemini-2.5-flash-lite",
    "llmTemperature": 0.7,

    "sttProvider": "deepgram",
    "sttModel": "nova-3",
    "sttConfig": {
      "endpointing": 300,
      "interimResults": true
    },

    "ttsProvider": "cartesia",
    "ttsVoice": "95856005-0332-41b0-935f-352e296aa0df",

    "prompt": "You are a helpful customer support agent for Acme Corp. Keep responses brief and friendly.",

    "greetingMessage": "Hello! Thanks for calling Acme. How can I help you today?",
    "allowInterruptions": true,

    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_order_status",
          "description": "Look up an order by ID",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": {"type": "string"}
            },
            "required": ["order_id"]
          }
        }
      }
    ],

    "webhooks": {
      "url": "https://api.example.com/webhooks/voice",
      "events": ["call.ended"]
    },

    "recording": {
      "enabled": true,
      "format": "mp3"
    }
  }
}

Next Steps#

Was this page helpful?