Troubleshooting Guide

# Check if tool reference exists
Check: agentSettings.tools array contains entry with nodeId matching your node

# Steps to fix:
1. Go to Tools page
2. Verify tool exists and is active
3. Check tool has valid configuration
4. Re-add tool to node in flow builder
5. Save agent

# In node configuration:
Parameters:
  - name: required_param
    value: { { valid_variable } } # Ensure variable exists
    required: true

Tool Node Configuration:
  timeout: 30000 # Increase from default (30s) to 60s
  onErrorBehavior: continue # Don't fail the call

Tool Node:
  processingMessage: 'This may take a moment, please hold...'
  processingMessageType: static

# In Flow Builder:
1. Click on tool node
2. Click "Test Tool" button
3. Provide sample parameters
4. Review response and errors

# Common issues:
❌ Wrong: url: "api.example.com/users"
✅ Right: url: "https://api.example.com/users"

❌ Wrong: headers: { "Authorization": "{{api_key}}" }
✅ Right: headers: { "Authorization": "Bearer {{api_key}}" }

# If output mapping fails:
Output Mapping:
  user_id: $.data.id # Check JSON path is correct
  user_name: $.data.name # Use Test Tool to see actual response structure

# Full override support:
Tool Reference (in agentSettings.tools):
  toolType: 'FUNCTION'
  overrides:
    url: 'https://custom-api.example.com'
    method: 'POST'
    parameters:
      custom_param: { { my_variable } }
    headers:
      Authorization: 'Bearer {{api_key}}'
    timeout: 15000

# Limited override support:
Tool Reference (in agentSettings.tools):
  toolType: 'WEB_TOOL'
  overrides:
    name: 'Custom Tool Name' # Only name, description, params
    description: 'Modified description'
    parameters:
      param1: { { custom_value } }
  # Cannot override: URL, method, headers, timeout

# No overrides allowed:
Tool Reference (in agentSettings.tools):
  toolType: 'MCP'
  # MCP tools are server-managed
  # No overrides field available

# In agentSettings.tools:
Tool Reference:
  persistentId: 'my-tool'
  toolId: 'uuid-v1'
  version: 1
# If tool was updated in library:
# version is now 2, causing mismatch

# Steps:
1. Go to Tools page
2. Find the tool
3. Check current version
4. In Flow Builder, click "Sync Tool Version" button
5. Review changes
6. Test agent after syncing

Conversation Node:
  extractVariables:
    enabled: true # Must be true
    variables:
      - name: customer_name
        description: "Customer's full name"
        dataType: string
        extractionPrompt: "Extract the customer's full name from the conversation"
        isRequired: true

Variable Configuration:
  extractionMethod: llm_function_calling # Most reliable
  confidenceThreshold: 0.8 # Lower if extraction fails (0.0-1.0)
  retryAttempts: 2 # Increase if first attempt fails

# Variable extraction requires:
1. User actually provided the information
2. Conversation node had user interaction
3. Extraction prompt is clear and specific

# Example:
Node Prompt: "What is your account number?"
User says: "It's 12345"
Extraction works: ✅

Node Prompt: "Welcome!"
User says: "Hi"
Extraction fails: ❌ (no account number mentioned)

❌ Wrong: {{customerName}}     # camelCase
❌ Wrong: {{customer-name}}    # hyphen
✅ Right: {{customer_name}}    # snake_case

❌ Wrong: {{ customer_name }}  # spaces
✅ Right: {{customer_name}}    # no spaces

# Variables must be:
1. Extracted in a previous node
2. Set via output mapping from a tool
3. A system variable
4. Created as custom variable

# Check Variables Panel:
- Open Variables Panel in Flow Builder
- Verify variable appears in list
- Check variable has a value

# Variable must be available at point of use:
[Start Node] → extracts customer_name ✅
  → [Node 2] → can use {{customer_name}} ✅
  → [Node 3] → can use {{customer_name}} ✅

# But:
[Node 2] → tries to use {{order_id}} ❌
[Node 3] → extracts order_id ✅
# order_id not available in Node 2!

Variable Configuration:
  name: priority_level
  dataType: string
  enumValues:
    - 'high' # Must match exactly
    - 'medium'
    - 'low'
  extractionPrompt: "Extract priority as 'high', 'medium', or 'low' (lowercase)"
# Common issue: User says "High" but enum is "high"
# Solution: Include in extraction prompt to specify case

# 14 Built-in Context Rules:
1. call_duration_seconds → Elapsed time tracking
2. conversation_turn_count → Interaction counting
3. previous_node_id → Navigation history
4. user_sentiment → Emotional state detection
5. conversation_topic → Subject tracking
6. user_intent → Goal detection
7. information_completeness → Data collection progress
8. customer_value_tier → Segmentation
9. urgency_level → Priority detection
10. technical_complexity → Issue classification
11. authentication_status → Security state
12. language_detected → Multilingual support
13. business_hours_status → Time-based routing
14. queue_position → Call center integration

# Context rules are automatic
# Ensure agent prompt references them:
Prompt: "Consider the {{user_sentiment}} and {{urgency_level}} when responding"

# DTMF Requirements:
- Phone carrier must support DTMF tones
- SIP trunk must pass DTMF (RFC 2833 or SIP INFO)
- Test with different phone/provider

Conversation Node:
  transitions:
    - type: dtmf
      key: '1'
      targetNodeId: sales_node

    - type: dtmf
      key: '2'
      targetNodeId: support_node

❌ Problem:
Conversation Node:
  dtmfInputCapture:
    enabled: true  # Capturing all digits
    variableName: account_number
  transitions:
    - dtmf: key=1  # Won't work! Number keys reserved for capture

✅ Solution: Use non-number keys for navigation
  transitions:
    - dtmf: key=#  # Use # or * for navigation
    - dtmf: key=*

Conversation Node:
  message: 'Please enter your 8-digit account number followed by the pound key'
  dtmfInputCapture:
    enabled: true
    variableName: account_number
    digitLimit: 8 # Stop after 8 digits
    terminationKey: '#' # Or stop when # is pressed
    timeoutMs: 20000 # 20 seconds to enter

# Option 1: Digit Limit (fixed length)
digitLimit: 8        # For SSN, account numbers
terminationKey: null # Optional

# Option 2: Termination Key (variable length)
digitLimit: null           # No fixed limit
terminationKey: "#"        # User presses # when done

# Option 3: Both (either condition stops)
digitLimit: 16             # Maximum 16 digits
terminationKey: "#"        # Or # to finish early

Router Node:
  transitions:
    - equation: {{account_number}}.length == 8
      targetNode: valid_account
    - equation: {{account_number}}.length != 8
      targetNode: retry_input

# DTMF Navigation is for OUTBOUND calls only
Global Settings:
  dtmfNavigation:
    enabled: true
    instructions: |
      Listen for IVR menu options like "Press 1 for Sales, Press 2 for Support".
      Press the appropriate key to navigate.
      If you hear "Press 0 for operator", press 0.
    digitDelay: 500 # Wait 500ms between keypress
    autoOperator: true # Automatically press 0 if menu is complex
    maxRetries: 3 # Retry up to 3 times if navigation fails

# Transitions are evaluated TOP TO BOTTOM
Transitions:
  - Natural Language: "user wants sales" → Sales_Node        # Checked first
  - Equation: {{budget}} > 5000 → High_Value_Node           # Checked second
  - DTMF: key=1 → Option_1                                  # Checked third
  - Always → Default_Node                                   # Last resort

# Always put "Always" transition LAST

❌ Wrong: {{customer_age}} >= 18
✅ Right: {{customer_age}} >= 18

❌ Wrong: if ({{status}} == "active") { }
✅ Right: {{status}} == "active"

❌ Wrong: {{first_name}} + " " + {{last_name}}
✅ Right: Use tool or custom variable for concatenation

# Natural language transitions use LLM to evaluate
# Make conditions specific:

❌ Vague: "user is done"
✅ Specific: "user confirmed they want to complete the purchase"

❌ Vague: "user has question"
✅ Specific: "user asked a question about pricing or features"

# Number comparison:
✅ {{age}} >= 18                    # age is number
❌ {{age_string}} >= 18             # age_string is "18" (string)

# String comparison:
✅ {{status}} == "active"           # Both strings
❌ {{status}} == active             # Missing quotes

# Boolean comparison:
✅ {{is_verified}} == true
❌ {{is_verified}} == "true"        # String, not boolean

# Check existence first:
✅ {{customer_name}} != null AND {{customer_name}} != ""
❌ {{customer_name}}.length > 0    # Crashes if null

# Use default values:
✅ ({{score}} ?? 0) > 50            # Default to 0 if undefined

# Break complex conditions into multiple transitions:

❌ Complex:
{{age}} >= 18 AND {{income}} > 50000 AND ({{credit_score}} > 700 OR {{has_cosigner}} == true)

✅ Better: Multiple transitions in order
- Equation: {{age}} >= 18 AND {{income}} > 50000 AND {{credit_score}} > 700 → Approved
- Equation: {{age}} >= 18 AND {{income}} > 50000 AND {{has_cosigner}} == true → Approved_Cosigner
- Always → Denied

Model Settings:
  provider: 'groq' # Fastest
  model: 'mixtral-8x7b' # Fast model
  maxTokens: 500 # Limit response length
  temperature: 0.3 # More deterministic (faster)

# Minimize tool calls in conversation:
❌ Bad: Tool call for every piece of data
✅ Good: One tool call to fetch all needed data

# Use output mapping to extract multiple variables:
Tool Node:
  outputMapping:
    name: $.data.name
    email: $.data.email
    phone: $.data.phone
    # Get all data in one call

# Shorter prompts = faster response:
❌ Long: 500-word detailed instructions
✅ Short: 100-word focused objective

# Use static messages for fixed content:
messageType: static
message: 'Thank you for calling Acme Corp.'
# No LLM processing needed

# Global interrupt setting (applies to all nodes):
Global Settings:
  interrupt: true   # Allow interruptions (default)

# For specific nodes that need uninterrupted delivery:
Conversation Node:
  skipResponse: false
  # User can interrupt by default

# For announcements:
Conversation Node:
  skipResponse: true  # Auto-advance, no interruption possible
  message: "Please hold while I transfer you..."

❌ Problem:
Node A → Natural Language: "anything" → Node B
Node B → Natural Language: "anything" → Node A
# Creates infinite loop!

✅ Solution: Add exit condition
Node A → Natural Language: "user wants to exit" → End_Call
Node A → Natural Language: "user needs help" → Node B
Node B → Natural Language: "task complete" → Summary_Node
Node B → Natural Language: "user confused" → Node A (with counter)

# Create custom variable to track attempts:
Router Node:
  transitions:
    - equation: {{retry_count}} >= 3 → Escalate_To_Human
    - equation: {{retry_count}} < 3 → Try_Again

# Increment counter in tool or conversation node

# Every flow should have:
Global Node:
  globalCondition: 'user says exit, quit, goodbye, or stop'
  targetNode: End_Call_Node
# Ensures user can always exit

# In Call History:
1. Find the call
2. Open Call Details
3. Go to Logs tab
4. Look for node transitions:
   - "Entered node: Node_A"
   - "Evaluating transitions..."
   - "Transition matched: Node_C"  # Skipped Node_B!

# Ensure intended path is possible:
Node A:
  transitions:
    - Natural Language: "specific condition" → Node B
    - Always → Node C  # This catches everything else!

# If condition isn't matched, goes to Node C (skipping B)

# Test each transition:
1. Use Test Agent feature
2. Try exact phrases for each transition
3. Verify each path is reachable
4. Check for unreachable nodes (gray in canvas)

Global Node:
  isGlobal: true                    # Must be true
  globalConditionType: "prompt"     # Or "dtmf"
  globalCondition: "user wants to speak to a human operator"

# For DTMF:
  globalConditionType: "dtmf"
  globalDtmfKey: "0"

❌ Vague: "user has question"
✅ Specific: "user explicitly requests human assistance or operator"

❌ Vague: "user frustrated"
✅ Specific: "user expresses frustration, anger, or dissatisfaction and wants human help"

# In Test Agent:
1. Start conversation
2. At any point say exact trigger phrase
3. Should immediately transition to global node

# If doesn't work:
- Rephrase global condition
- Make condition more specific
- Test with different trigger phrases

# Check API key location:
1. Project Settings → API Keys
2. Verify key is active
3. Check key hasn't expired
4. Regenerate if necessary

# For tool authentication:
Tool Configuration:
  headers:
    Authorization: "Bearer {{api_key}}"  # Correct format

# Ensure api_key variable is set or use direct value

Tool Node:
  onErrorBehavior: 'retry'
  retryAttempts: 3
  errorMessage: 'Having trouble connecting, trying again...'

# Cache frequent lookups:
- Customer data: Cache for 5 minutes
- Product catalog: Cache for 1 hour
- System settings: Cache for 24 hours

# Batch operations:
- Fetch multiple records in single API call
- Use webhooks for notifications instead of polling
- Implement queue for non-urgent operations

# Browser must allow:
- Microphone access
- Audio playback
- WebRTC connections
# Chrome: Settings → Privacy → Site Settings → Microphone
# Firefox: Preferences → Privacy & Security → Permissions

# Agent must have:
- At least one start node
- Valid flow (no isolated nodes)
- All required fields filled
- No validation errors

# Test requires:
- Stable internet connection
- WebRTC not blocked by firewall
- No VPN interfering with WebRTC

❌ Bloated:
Prompt: "You are an extremely helpful, very professional, highly trained,
world-class customer service representative with years of experience working
at Fortune 500 companies, specializing in providing exceptional support..."

✅ Concise:
Prompt: "Professional customer service agent. Be helpful and concise."

# Match model to task complexity:
Simple confirmation: GPT-4.1-Mini
Complex reasoning: GPT-4.1
Balance: GPT-4o-mini

Model Settings:
  maxTokens: 200 # Shorter responses
  temperature: 0.2 # More focused (fewer tokens)

# In Telephony Settings:
1. Verify phone number is purchased and active
2. Check phone number is assigned to this agent
3. Confirm routing rules are correct
4. Test with call forwarding

# Agent must be:
- Published (not draft)
- Active (not paused)
- Valid configuration
- No critical errors