> ## 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

<ParamField path="agent_id" type="string" required>
  UUID of the agent to update.
</ParamField>

***

## Body Parameters

<ParamField body="conversational_experience" type="object">
  Settings that shape how the agent sounds and behaves during a conversation.

  <Expandable title="conversational_experience fields">
    <ParamField body="bg_noise" type="object">
      Background noise overlay.

      <Expandable title="bg_noise fields">
        <ParamField body="enabled" type="boolean">Turn background noise on or off.</ParamField>
        <ParamField body="volume" type="number">Volume level (0–1).</ParamField>
        <ParamField body="sound" type="string">Sound preset name (e.g. `"office"`, `"cafe"`).</ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="filler_words" type="object">
      Natural filler words injected into speech.

      <Expandable title="filler_words fields">
        <ParamField body="filler_words_frequency" type="number">
          How often to insert filler words (0–1, where 0 = never).
        </ParamField>

        <ParamField body="filler_words_list" type="array">
          Custom list of filler words (e.g. `["um", "uh", "you know"]`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="eagerness_to_speak" type="string">
      How quickly the agent starts speaking after the user stops: `"slow"` | `"balanced"` | `"fast"`.
    </ParamField>

    <ParamField body="breathing_sound" type="object">
      Breathing sound configuration (provider-specific shape).
    </ParamField>

    <ParamField body="patience_with_user_entries" type="object">
      Configuration for how long the agent waits for incomplete user input.
    </ParamField>

    <ParamField body="mood_mapping" type="object">
      Map of detected moods to behavioural adjustments.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="settings" type="object">
  Call-level operational settings.

  <Expandable title="settings fields">
    <ParamField body="idle_conversation_settings" type="object">
      What the agent does when the call goes quiet.

      <Expandable title="idle_conversation_settings fields">
        <ParamField body="pulse_check" type="boolean">Send a prompt to check if user is still there.</ParamField>
        <ParamField body="end_conversation_on_idle" type="boolean">Hang up after idle timeout.</ParamField>
        <ParamField body="idle_call_hangup_timeout" type="integer">Seconds of silence before hanging up (5–60).</ParamField>
        <ParamField body="idle_call_warning_timeout" type="integer">Seconds of silence before warning the user (5–60).</ParamField>
        <ParamField body="idle_call_hangup_message" type="string">Message played before hanging up.</ParamField>
        <ParamField body="idle_call_warning_message" type="string">Message played as the idle warning.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="end_call" type="object">
      Automatic hang-up on a phrase.

      <Expandable title="end_call fields">
        <ParamField body="enabled" type="boolean">Enable phrase-based call ending.</ParamField>
        <ParamField body="end_call_phrase" type="string">Phrase that triggers the hang-up (e.g. `"goodbye"`).</ParamField>
        <ParamField body="hangup_timeout" type="integer">Seconds to wait after the phrase before hanging up.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="call_settings" type="object">
      Global call limits.

      <Expandable title="call_settings fields">
        <ParamField body="max_call_duration" type="integer">Maximum call duration in minutes (1–60).</ParamField>
        <ParamField body="max_duration_enabled" type="boolean">Enforce the max duration limit.</ParamField>
        <ParamField body="enable_voicemail_detection" type="boolean">Enable voicemail / answering-machine detection.</ParamField>
        <ParamField body="action" type="string">What to do if voicemail is detected: `"hang_up"` | `"leave_message"`.</ParamField>
        <ParamField body="end_call_message" type="string">Message to leave if action is `"leave_message"`.</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

***

## Request Example

<RequestExample>
  ```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!",
              }
          },
      },
  )
  ```
</RequestExample>

***

## Response

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "success": true,
    "message": "Experience section updated successfully"
  }
  ```
</ResponseExample>