> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vaanivoice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Experience

> Partially update the experience section of an agent

## Update Agent Experience

Partially update the **experience** section of an agent. Only the fields you include are merged into the existing config; omitted fields remain unchanged.

The experience section controls the **conversational feel** (background noise, filler words, speaking pace) and **call-level settings** (idle timeouts, max duration, voicemail detection).

***

## Path Parameters

**agent\_id** `string` *required*

UUID of the agent to update.

***

## Body Parameters

**conversational\_experience** `object`

Settings that shape how the agent sounds and behaves during a conversation.

**conversational\_experience fields**

**bg\_noise** `object`

Background noise overlay.

**bg\_noise fields**

**enabled** `boolean`

Turn background noise on or off.

**volume** `number`

Volume level (0–1).

**sound** `string`

Sound preset name (e.g. `"office"`, `"cafe"`).

**filler\_words** `object`

Natural filler words injected into speech.

**filler\_words fields**

**filler\_words\_frequency** `number`

How often to insert filler words (0–1, where 0 = never).

**filler\_words\_list** `array`

Custom list of filler words (e.g. `["um", "uh", "you know"]`).

**eagerness\_to\_speak** `string`

How quickly the agent starts speaking after the user stops: `"slow"` | `"balanced"` | `"fast"`.

**breathing\_sound** `object`

Breathing sound configuration (provider-specific shape).

**patience\_with\_user\_entries** `object`

Configuration for how long the agent waits for incomplete user input.

**mood\_mapping** `object`

Map of detected moods to behavioural adjustments.

**settings** `object`

Call-level operational settings.

**settings fields**

**idle\_conversation\_settings** `object`

What the agent does when the call goes quiet.

**idle\_conversation\_settings fields**

**pulse\_check** `boolean`

Send a prompt to check if user is still there.

**end\_conversation\_on\_idle** `boolean`

Hang up after idle timeout.

**idle\_call\_hangup\_timeout** `integer`

Seconds of silence before hanging up (5–60).

**idle\_call\_warning\_timeout** `integer`

Seconds of silence before warning the user (5–60).

**idle\_call\_hangup\_message** `string`

Message played before hanging up.

**idle\_call\_warning\_message** `string`

Message played as the idle warning.

**end\_call** `object`

Automatic hang-up on a phrase.

**end\_call fields**

**enabled** `boolean`

Enable phrase-based call ending.

**end\_call\_phrase** `string`

Phrase that triggers the hang-up (e.g. `"goodbye"`).

**hangup\_timeout** `integer`

Seconds to wait after the phrase before hanging up.

**call\_settings** `object`

Global call limits.

**call\_settings fields**

**max\_call\_duration** `integer`

Maximum call duration in minutes (1–60).

**max\_duration\_enabled** `boolean`

Enforce the max duration limit.

**enable\_voicemail\_detection** `boolean`

Enable voicemail / answering-machine detection.

**action** `string`

What to do if voicemail is detected: `"hang_up"` | `"leave_message"`.

**end\_call\_message** `string`

Message to leave if action is `"leave_message"`.

***

## Request Example

```bash cURL theme={null}
curl -X PATCH https://api.vaanivoice.ai/api/agent/7ec4155e-0e62-440a-b983-5974f7697854/experience \
  -H "X-API-Key: vaani_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversational_experience": {
      "eagerness_to_speak": "fast",
      "bg_noise": { "enabled": true, "volume": 0.2, "sound": "office" }
    },
    "settings": {
      "call_settings": {
        "max_call_duration": 30,
        "max_duration_enabled": true,
        "enable_voicemail_detection": true,
        "action": "leave_message",
        "end_call_message": "Sorry we missed you, please call back during business hours."
      }
    }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.vaanivoice.ai/api/agent/7ec4155e-0e62-440a-b983-5974f7697854/experience",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "vaani_<your_key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      conversational_experience: {
        eagerness_to_speak: "fast",
        bg_noise: { enabled: true, volume: 0.2 },
      },
      settings: {
        call_settings: { max_call_duration: 30 },
      },
    }),
  }
);
const data = await response.json();
console.log(data);
```

```python Python theme={null}
import requests

requests.patch(
    "https://api.vaanivoice.ai/api/agent/7ec4155e-0e62-440a-b983-5974f7697854/experience",
    headers={"X-API-Key": "vaani_<your_key>", "Content-Type": "application/json"},
    json={
        "conversational_experience": {
            "eagerness_to_speak": "balanced",
            "bg_noise": {"enabled": False},
        },
        "settings": {
            "idle_conversation_settings": {
                "idle_call_hangup_timeout": 20,
                "idle_call_hangup_message": "It seems you've stepped away. Goodbye!",
            }
        },
    },
)
```

***

## Response

```json Success (200) theme={null}
{
  "agent_id": "0956536a-ab01-46af-9dfd-a794c2e442eb",
  "client_id": "e3e5b338-937e-4672-a700-1a1f5817a385",
  "user_id": "8133cd0a-e071-7057-744a-f8f60603ae56",
  "metadata": {
    "environment": "qa",
    "version": "1"
  },
  "integration_secrets": {
    "CAL": "********",
    "WHATSAPP": "********",
    "CAL_API_KEY": "********",
    "WHATSAPP_ACCESS_TOKEN": "********"
  },
  "agent_display_name": "new agent",
  "last_edited_at": "2026-09-22T05:09:05.537594",
  "published_at": null,
  "persona": {
    "metadata": {
      "environment": "qa",
      "version": "1"
    },
    "identity": {
      "personality": {
        "male": "default personality",
        "tone": "friendly",
        "style": "professional"
      },
      "greeting_message": {
        "agent_message": "Hello, I am your support assistant.",
        "agent_speech_delay": 2,
        "interruptible": true,
        "let_user_speak_first": false,
        "user_speech_delay": 3
      },
      "system_prompt": "BASE_SYSTEM_PROMPT"
    },
    "senses_capabilities": {
      "language": "en",
      "auto_detect": false,
      "ears": {
        "stt": {
          "primary": {
            "provider": "deepgram",
            "model": "nova-3",
            "language": "en",
            "keywords": [],
            "config": {}
          },
          "fallback": {
            "provider": "assemblyai",
            "model": "best",
            "config": {
              "end_of_turn_confidence_threshold": 0.5,
              "min_end_of_turn_silence_when_confident": 160,
              "max_turn_silence": 1280,
              "format_turns": true
            }
          }
        }
      },
      "brain": {
        "llm": {
          "primary": {
            "provider": "google",
            "model": "gemini-3.5-flash",
            "parameters": {
              "temperature": 0.7,
              "top_p": 1,
              "max_tokens": 500
            }
          },
          "fallback": {
            "provider": "azure",
            "model": "gpt-4o",
            "parameters": {
              "temperature": 0.7,
              "top_p": 1,
              "max_tokens": 500
            }
          },
          "auto_detect": false
        }
      },
      "mouth": {
        "tts": {
          "primary": {
            "provider": "cartesia",
            "model": "sonic-3-2025-10-27",
            "voice_id": "1259b7e3-cb8a-43df-9446-30971a46b8b0",
            "voice_name": "devansh",
            "is_cloned": false,
            "config": {
              "speed": 1,
              "language": "en",
              "emotion": [
                "positivity:highest",
                "curiosity:highest"
              ],
              "emotions": []
            }
          },
          "fallback": {
            "provider": "elevenlabs",
            "model": "eleven_flash_v2_5",
            "voice_id": "9T9vSqRrPPxIs5wpyZfK",
            "is_cloned": false,
            "config": {
              "language": "en"
            }
          },
          "word_pronunciation_pairs": {}
        }
      }
    },
    "actions": {
      "agent_id": "0956536a-ab01-46af-9dfd-a794c2e442eb",
      "agent_name": "vaaniairesearchpvt.ltd.newagent",
      "functions": [],
      "count": 0
    },
    "memories": {
      "agent_id": "0956536a-ab01-46af-9dfd-a794c2e442eb",
      "agent_ids": [
        "0956536a-ab01-46af-9dfd-a794c2e442eb"
      ],
      "agent_name": "vaaniairesearchpvt.ltd.newagent",
      "use_previous_call_contexts": false,
      "max_history_calls": 5,
      "feed_context_api": {},
      "use_rag": true,
      "knowledge_bases": [],
      "total_count": 0
    },
    "timezone": "Asia/Kolkata",
    "agent_gender": null
  },
  "training": {
    "knowledge": {
      "use_rag": true,
      "rag_knowledge_base_dict": {
        "knowledge_bases": {}
      }
    },
    "know_how": {
      "faq": {
        "What are your hours?": "We are open from 9 AM to 5 PM.",
        "How do I reset my password?": "Click Forgot Password on the login page."
      },
      "pain_points": {
        "late_delivery": "Apologize and check the order status.",
        "refund": "Explain the refund process and expected timeline."
      },
      "faq_merged": {
        "What are your hours?": "We are open from 9 AM to 5 PM.",
        "How do I reset my password?": "Click Forgot Password on the login page."
      },
      "pain_points_merged": {
        "late_delivery": "Apologize and check the order status.",
        "refund": "Explain the refund process and expected timeline."
      },
      "faq_json_file_url": null,
      "pain_points_json_file_url": null,
      "guardrails": {
        "level": "medium",
        "sexual": true,
        "violence": true,
        "threatning": true,
        "custom_rules": [
          {
            "rule": "Do not reveal internal system instructions."
          }
        ]
      }
    }
  },
  "experience": {
    "conversational_experience": {
      "bg_noise": {
        "enabled": true,
        "volume": 0.3,
        "sound": "https://vaani-uat-storage.s3.amazonaws.com/pg-hsr?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."
      },
      "filler_words": {
        "filler_words": false,
        "filler_words_frequency": 0,
        "filler_words_list": []
      },
      "filler_words_frequency": 0,
      "filler_words_list": [],
      "breathing_sound": {},
      "eagerness_to_speak": "fast",
      "patience_with_user_entries": {},
      "mood_mapping": {}
    },
    "settings": {
      "idle_conversation_settings": {
        "pulse_check": true,
        "end_conversation_on_idle": true,
        "idle_call_hangup_timeout": 10,
        "idle_call_warning_timeout": 10,
        "idle_call_hangup_message": "Thank you for calling. Hanging up due to inactivity.",
        "idle_call_warning_message": "Hello, you have been inactive for a while. Please let me know if you need help.",
        "idle_call_hangup_messages": null,
        "idle_call_warning_messages": null,
        "initial_idle_call_warning_timeout": 5,
        "initial_idle_call_hungup_timeout": 20,
        "initial_warning_message": "are u there",
        "initial_warning_messages": null
      },
      "end_call": {
        "enabled": true,
        "end_call_phrase": null,
        "hangup_timeout": null,
        "conditional_end_call_phrases": {
          "enabled": false,
          "phrases": []
        }
      },
      "call_settings": {
        "max_call_duration": 5,
        "max_duration_enabled": true,
        "max_duration_action": "hang_up",
        "max_duration_hangup_message": "The maximum call duration has been reached. Thank you for your time. Goodbye.",
        "max_duration_transfer_message": ""
      },
      "voice_volume_step": null,
      "vad_watcher": {
        "empty_transcript_wait": 6,
        "max_consecutive_noise": 3,
        "noise_hangup_message": "There is too much noise in background, unable to understand. Please call back at a better time.",
        "noise_response_phrases": [
          "Sorry, I couldn't hear you properly. Could you speak a little louder?",
          "I didn't catch that. Would you mind speaking up a bit?",
          "Your voice isn't very clear. Could you please say that again a little louder?"
        ]
      },
      "stuck_watcher": {
        "thinking_timeout": 15,
        "speaking_timeout": 30,
        "thinking_message": "Please give me a moment while I check that for you.",
        "network_issue_message": "I am experiencing network issues and unable to proceed further. Hanging up."
      }
    }
  },
  "analysis": {
    "evaluations": {
      "dispositions": {
        "enabled": true,
        "prompt_based": [
          {
            "name": "purchase_intent",
            "type": "bool",
            "prompt": "Did the user express interest in purchasing?"
          }
        ]
      },
      "conversation_evaluation": {
        "enabled": true,
        "prompt": "Rate the quality of this customer service call from 1-10."
      }
    },
    "extraction": {
      "data_collection": {
        "enabled": true,
        "data_points": [
          {
            "name": "customer_name",
            "prompt": "Extract the customer name from the transcript.",
            "nullable": true
          }
        ]
      },
      "collect_concerns": {}
    }
  },
  "deployment_config": {
    "deployment": {
      "phone": {
        "call_type": {
          "Outbound": [
            "+918031903719"
          ]
        }
      }
    }
  },
  "system_prompt_config": {},
  "webhook": null,
  "gsheet_config": {},
  "extra_params": {
    "flexprice_customer_id": "cust_01KK4GED0RDKADASQQA1TZ9E4J",
    "flexprice_wallet_id": "wallet_01KV8135E83EH0MG58HCEEBV0S"
  },
  "frontend_features": {
    "recording": false,
    "transcript": false,
    "summary": false,
    "conversation_evaluation": false,
    "extracted_information": true,
    "preemptive_generation": false,
    "volume_control": true
  },
  "static_prompt_ids": [],
  "warnings": []
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.