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

# Update Voice Agent

> Update Voice AI agent with comprehensive configuration options

## Overview

Update an existing Voice agent's configuration including voice settings, conversation behavior, voicemail handling, and AI behavior. All parameters from [Create Voice Agent](/partner-api/agents/create-voice) can be updated.

<Note>
  This endpoint is for **Voice agents only**. For SMS agents, see [Update SMS Agent](/partner-api/agents/update-sms).

  For updating **tools** (function calling, transfers, etc.), use [Update Voice Agent Tools](/partner-api/agents/update-tools).
</Note>

***

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your Teli API key
</ParamField>

***

## Path Parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier of the Voice agent to update
</ParamField>

***

## Request Body

All fields are optional. Only include the fields you want to update.

***

### Basic Settings

<ParamField body="agent_name" type="string">
  Display name for the agent
</ParamField>

<ParamField body="starting_message" type="string">
  First message spoken when call connects. Supports `{{first_name}}`, `{{last_name}}`
</ParamField>

<ParamField body="prompt" type="string">
  AI behavior instructions defining personality and conversation goals
</ParamField>

***

### Voice Configuration

<ParamField body="voice_id" type="string">
  Voice ID for text-to-speech. See [List Voices](/partner-api/voices/list) for options.
</ParamField>

<ParamField body="voice_temperature" type="number" default="1">
  Voice stability. Range: 0 (stable) to 2 (varied)
</ParamField>

<ParamField body="voice_speed" type="number" default="1">
  Speech rate. Range: 0.5 (slow) to 2 (fast)
</ParamField>

<ParamField body="volume" type="number" default="1">
  Agent volume. Range: 0 (quiet) to 2 (loud)
</ParamField>

***

### Language

<ParamField body="language" type="string" default="en-US">
  Speech recognition language
</ParamField>

**Supported languages:**

* `en-US` (English - US)
* `en-GB` (English - UK)
* `es-ES` (Spanish - Spain)
* `es-419` (Spanish - Latin America)
* `fr-FR` (French)
* `de-DE` (German)
* `ja-JP` (Japanese)
* `zh-CN` (Chinese)
* `multi` (Multilingual)

***

### Conversation Behavior

<ParamField body="responsiveness" type="number" default="1">
  How quickly agent responds. Range: 0 (slower) to 1 (faster)
</ParamField>

<ParamField body="interruption_sensitivity" type="number" default="1">
  How easily user can interrupt. Range: 0 (hard) to 1 (easy)
</ParamField>

<ParamField body="enable_backchannel" type="boolean" default="false">
  Enable conversational interjections ("yeah", "uh-huh")
</ParamField>

<ParamField body="backchannel_frequency" type="number" default="0.8">
  How often to interject. Range: 0 (rarely) to 1 (frequently)
</ParamField>

<ParamField body="backchannel_words" type="array">
  Custom backchannel words. Example: `["right", "I see", "got it"]`
</ParamField>

***

### Ambient Sound

<ParamField body="ambient_sound" type="string">
  Background audio for realism
</ParamField>

**Options:**

* `null` - No ambient sound
* `coffee-shop` - Café atmosphere
* `convention-hall` - Echo, crowd noise
* `summer-outdoor` - Cicadas, nature
* `mountain-outdoor` - Birds, wind
* `static-noise` - Light static
* `call-center` - Office background

<ParamField body="ambient_sound_volume" type="number" default="1">
  Ambient sound level. Range: 0 to 2
</ParamField>

***

### Voicemail Detection

<ParamField body="enable_voicemail_detection" type="boolean" default="true">
  Automatically detect voicemail
</ParamField>

<ParamField body="voicemail_message" type="string">
  Message to leave on voicemail. Empty string = hangup immediately
</ParamField>

<ParamField body="voicemail_detection_timeout_ms" type="number" default="30000">
  Detection timeout in milliseconds. Range: 5000 to 180000
</ParamField>

***

### Reminder & Silence Settings

<ParamField body="reminder_trigger_ms" type="number" default="10000">
  Time (ms) to wait before reminding silent user
</ParamField>

<ParamField body="reminder_max_count" type="number" default="1">
  Maximum reminders before ending call. 0 = disabled
</ParamField>

<ParamField body="end_call_after_silence_ms" type="number" default="90000">
  End call after this much silence (ms). Minimum: 10000
</ParamField>

***

### Call Settings

<ParamField body="max_call_duration_ms" type="number" default="3600000">
  Maximum call length in milliseconds. Range: 60000 to 7200000
</ParamField>

<ParamField body="begin_message_delay_ms" type="number" default="0">
  Delay before speaking (ms). Range: 0 to 5000
</ParamField>

<ParamField body="ring_duration_ms" type="number" default="30000">
  Ring timeout for outbound calls (ms). Range: 5000 to 90000
</ParamField>

***

### Speech Recognition

<ParamField body="stt_mode" type="string" default="fast">
  Speech-to-text mode: `fast` or `accurate`
</ParamField>

<ParamField body="vocab_specialization" type="string" default="general">
  Vocabulary focus: `general` or `medical`
</ParamField>

<ParamField body="boosted_keywords" type="array">
  Words to boost recognition. Example: `["Acme", "TurboWidget"]`
</ParamField>

<ParamField body="normalize_for_speech" type="boolean" default="false">
  Convert numbers/dates to spoken form
</ParamField>

<ParamField body="allow_user_dtmf" type="boolean" default="true">
  Allow keypad input (press 1, press 2, etc.)
</ParamField>

<ParamField body="denoising_mode" type="string" default="noise-cancellation">
  Audio cleanup: `noise-cancellation` or `noise-and-background-speech-cancellation`
</ParamField>

***

### Knowledge Base

<ParamField body="knowledge_base_ids" type="array">
  Link knowledge bases for RAG retrieval. Example: `["kb_abc123"]`
</ParamField>

<ParamField body="kb_config" type="object">
  Knowledge base retrieval settings
</ParamField>

```json kb_config Example theme={null}
{
  "top_k": 3,           // Chunks to retrieve (1-10)
  "filter_score": 0.6   // Similarity threshold (0-1)
}
```

***

### Data Extraction (Post-Call Analysis)

Automatically extract custom data from call transcripts after each call ends.

<ParamField body="extraction_fields" type="array">
  List of field names to extract from conversations. Simple string array.

  Example: `["credit_score", "loan_amount", "annual_income", "interested"]`

  Extracted data is accessible via [GET /v1/voice/calls/{call_id}/extractions](/partner-api/call-history/extractions).
</ParamField>

<ParamField body="post_call_analysis_data" type="array">
  **Advanced:** Define custom fields with specific types. Use `extraction_fields` for simpler configuration.

  **String Type** - Extract free-form text:

  ```json theme={null}
  { "type": "string", "name": "customer_name", "description": "Full name of customer" }
  ```

  **Enum Type** - Extract from predefined choices:

  ```json theme={null}
  { "type": "enum", "name": "interest_level", "description": "Interest level", "choices": ["high", "medium", "low"] }
  ```

  **Boolean Type** - Extract true/false:

  ```json theme={null}
  { "type": "boolean", "name": "scheduled_callback", "description": "Agreed to callback" }
  ```

  **Number Type** - Extract numeric values:

  ```json theme={null}
  { "type": "number", "name": "budget", "description": "Stated budget amount" }
  ```
</ParamField>

***

### Privacy & Storage

<ParamField body="data_storage_setting" type="string" default="everything">
  What data to store
</ParamField>

**Options:**

* `everything` - Full transcripts, recordings, logs
* `everything_except_pii` - Scrub PII before storing
* `basic_attributes_only` - No transcripts/recordings

***

## Request Examples

### Update Voice Settings

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.teli.ai/v1/agents/agent_voice123" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "voice_speed": 0.9,
      "voice_temperature": 0.8,
      "responsiveness": 0.7,
      "interruption_sensitivity": 0.9
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.teli.ai/v1/agents/agent_voice123', {
    method: 'PATCH',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      voice_speed: 0.9,
      voice_temperature: 0.8,
      responsiveness: 0.7
    })
  });
  ```

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

  response = requests.patch(
      'https://api.teli.ai/v1/agents/agent_voice123',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'voice_speed': 0.9,
          'voice_temperature': 0.8,
          'responsiveness': 0.7
      }
  )
  ```
</CodeGroup>

***

### Update Conversation Behavior

```bash theme={null}
curl -X PATCH "https://api.teli.ai/v1/agents/agent_voice123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enable_backchannel": true,
    "backchannel_frequency": 0.6,
    "backchannel_words": ["right", "I see", "got it", "okay"],
    "ambient_sound": "call-center",
    "ambient_sound_volume": 0.5
  }'
```

***

### Update Voicemail Settings

```bash theme={null}
curl -X PATCH "https://api.teli.ai/v1/agents/agent_voice123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enable_voicemail_detection": true,
    "voicemail_message": "Hi {{first_name}}, this is Sarah from Acme Corp. Please call us back at 555-1234.",
    "voicemail_detection_timeout_ms": 25000
  }'
```

***

### Update AI Prompt & Knowledge Base

```bash theme={null}
curl -X PATCH "https://api.teli.ai/v1/agents/agent_voice123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are a helpful customer support agent. Be friendly and professional. Answer questions using the knowledge base when available.",
    "knowledge_base_ids": ["kb_abc123", "kb_def456"],
    "kb_config": {
      "top_k": 5,
      "filter_score": 0.7
    }
  }'
```

***

### Update Post-Call Analysis

```bash theme={null}
curl -X PATCH "https://api.teli.ai/v1/agents/agent_voice123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post_call_analysis_data": [
      {
        "type": "string",
        "name": "customer_name",
        "description": "The full name of the customer"
      },
      {
        "type": "enum",
        "name": "interest_level",
        "description": "How interested is the customer",
        "choices": ["very_interested", "somewhat_interested", "not_interested"]
      },
      {
        "type": "boolean",
        "name": "scheduled_callback",
        "description": "Whether the customer agreed to a callback"
      },
      {
        "type": "number",
        "name": "budget",
        "description": "The customer stated budget amount"
      }
    ],
    "post_call_analysis_model": "gpt-4.1-mini"
  }'
```

***

### Comprehensive Update

```json theme={null}
{
  "agent_name": "Premium Support Agent",
  "starting_message": "Hello {{first_name}}, thank you for calling Acme Support. How can I help you today?",
  "prompt": "You are a senior support specialist...",
  "voice_speed": 0.95,
  "voice_temperature": 0.7,
  "responsiveness": 0.8,
  "interruption_sensitivity": 0.9,
  "enable_backchannel": true,
  "backchannel_frequency": 0.5,
  "ambient_sound": "call-center",
  "reminder_max_count": 2,
  "end_call_after_silence_ms": 120000,
  "max_call_duration_ms": 1800000,
  "voicemail_message": "Hi, please call us back.",
  "knowledge_base_ids": ["kb_products", "kb_faq"]
}
```

***

## Response

### Success Response

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true,
    "agent_id": "agent_voice123",
    "message": "Agent updated successfully",
    "updated": {
      "voice_settings": true,
      "ai_behavior": true,
      "agent_info": true
    }
  }
  ```
</ResponseExample>

<ResponseField name="success" type="boolean">
  Indicates successful update
</ResponseField>

<ResponseField name="agent_id" type="string">
  The updated agent's unique identifier
</ResponseField>

<ResponseField name="updated.voice_settings" type="boolean">
  Whether voice/call settings were updated
</ResponseField>

<ResponseField name="updated.ai_behavior" type="boolean">
  Whether AI prompt/tools/knowledge base was updated
</ResponseField>

<ResponseField name="updated.agent_info" type="boolean">
  Whether agent metadata was updated
</ResponseField>

***

### Error Responses

<ResponseExample>
  ```json 404 - Agent Not Found theme={null}
  {
    "success": false,
    "error": "Agent not found"
  }
  ```

  ```json 500 - Partial Failure theme={null}
  {
    "success": false,
    "agent_id": "agent_voice123",
    "errors": ["Voice config update failed: Invalid voice_id"],
    "message": "Some updates failed - check errors for details"
  }
  ```
</ResponseExample>

***

## Use Case Presets

### Cold Calling / Sales

```json theme={null}
{
  "voice_speed": 1,
  "voice_temperature": 1,
  "responsiveness": 0.8,
  "interruption_sensitivity": 0.7,
  "enable_backchannel": true,
  "voicemail_message": "Hi {{first_name}}, this is calling from [Company]. Please call us back."
}
```

### Customer Support

```json theme={null}
{
  "voice_speed": 0.9,
  "voice_temperature": 0.8,
  "responsiveness": 0.6,
  "interruption_sensitivity": 0.9,
  "enable_backchannel": true,
  "backchannel_frequency": 0.7,
  "ambient_sound": "call-center",
  "reminder_max_count": 3
}
```

### Appointment Reminders

```json theme={null}
{
  "voice_speed": 1.1,
  "voice_temperature": 0.5,
  "responsiveness": 1,
  "max_call_duration_ms": 300000,
  "voicemail_message": "Hi {{first_name}}, this is a reminder about your appointment."
}
```

***

## Best Practices

<Check>
  **Test changes**: Test with a single call before updating production agents
</Check>

<Check>
  **Start conservative**: Begin with default values and adjust gradually
</Check>

<Check>
  **Match voice to persona**: Choose voice settings that match your agent's personality
</Check>

<Check>
  **Enable backchannel for long calls**: Makes conversations feel more natural
</Check>

<Check>
  **Set appropriate timeouts**: Adjust silence and reminder settings for your use case
</Check>

***

## Notes

<Warning>
  * Updates take effect immediately for **new calls**
  * Active calls continue with previous settings
  * Some settings (like `voice_id`) may take a few seconds to propagate
  * Agent type cannot be changed from Voice to SMS
</Warning>

***

## Related Endpoints

* [Create Voice Agent](/partner-api/agents/create-voice) - Create a new voice agent
* [Update Voice Agent Tools](/partner-api/agents/update-tools) - Manage function calling, transfers, etc.
* [Get Agent](/partner-api/agents/get) - Retrieve agent details
* [List Voices](/partner-api/voices/list) - Browse available voices
* [Create Knowledge Base](/partner-api/knowledge-bases/create) - Create KB for RAG