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

# Update Agent Voice

> Update an agent's voice settings and configuration

# Update Agent Voice

Update an agent's voice configuration including voice template, language, conversation speed, and other voice-related settings.

## Endpoint

```
PUT /api/v1/agents/{agent_id}/voice
```

## Path parameters

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

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`
</ParamField>

## Request body

<ParamField body="voice_id" type="string" required>
  Voice template ID. Use [List Voice Templates](/api-reference/endpoints/list-voice-templates) to retrieve available IDs.
</ParamField>

<ParamField body="conversation_speed" type="number" required>
  Conversation playback speed multiplier. Range: greater than `1`, less than `2`.
</ParamField>

<ParamField body="who_speaks_first" type="string" required>
  Who speaks first. Options: `agent`, `user`.
</ParamField>

<ParamField body="ambient_background" type="string">
  Ambient background sound for the conversation (e.g., `office`, `cafe`, `quiet`). Optional.
</ParamField>

<ParamField body="ambient_volume" type="number">
  Volume of the ambient background sound. Range: `0` (muted) to `2` (loud). Default: `1`.
</ParamField>

<ParamField body="language" type="string">
  Agent language code (e.g., `en-US`, `pt-BR`). Optional — only sent when changing the agent's spoken language. The voice template must support the chosen language.
</ParamField>

<ParamField body="similarity" type="number">
  Voice similarity boost. Range: `0.5` to `1.0`. **Required only for high-fidelity voice templates** (the `quality_tier` of the voice template determines whether this field is accepted). Higher values reinforce voice characteristics.
</ParamField>

<ParamField body="stability" type="number">
  Voice stability. Range: `0.5` to `1.0`. **Required only for high-fidelity voice templates**. Higher values produce more consistent output; lower values produce more expressive output.
</ParamField>

## Example requests

<RequestExample>
  ```bash theme={null}
  # Request 1: Update voice with settings
  curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "voice_id": "voice-template-uuid",
      "language": "en-US",
      "conversation_speed": 1.2,
      "ambient_background": "office",
      "who_speaks_first": "agent",
      "similarity": 0.75,
      "stability": 0.8
    }'
  ```

  ```javascript theme={null}
  // Request 1: Update voice with settings
  const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      voice_id: "voice-template-uuid",
      language: "en-US",
      conversation_speed: 1.2,
      ambient_background: "office",
      who_speaks_first: "agent",
      similarity: 0.75,
      stability: 0.8
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Request 2: Update voice with basic settings
  curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "voice_id": "basic-voice-uuid",
      "language": "en-US",
      "conversation_speed": 1.0,
      "who_speaks_first": "user"
    }'
  ```

  ```javascript theme={null}
  // Request 2: Update voice with basic settings
  const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/voice', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      voice_id: "basic-voice-uuid",
      language: "en-US",
      conversation_speed: 1.0,
      who_speaks_first: "user"
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Agent voice updated successfully",
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "SupportBot",
      "label": "Customer Support Agent",
      "description": "Handles customer inquiries and support requests",
      "language": "en-US",
      "voice": {
        "id": "voice-uuid",
        "name": "Bianca",
        "label": "Bianca Voice",
        "stability": 0.8,
        "similarity_boost": 0.75,
        "ambient_background": "office",
        "template": {
          "id": "voice-template-uuid",
          "name": "Bianca"
        }
      },
      "initial_message": "Hello, how can I help you today?",
      "interrupt_sensitivity": "medium",
      "conversation_speed": 1.2,
      "initial_message_delay": 0,
      "ask_if_human_present_on_idle": false,
      "direction": "inbound",
      "who_speaks_first": "agent",
      "current_status": "draft",
      "is_sandbox": false,
      "is_ready_to_publish": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:40:00Z",
      "trainings": [.],
      "actions": [.],
      "phone_numbers": [.]
    }
  }
  ```
</ResponseExample>

### Response fields

<ResponseField name="success" type="boolean" required>
  Indicates if the operation was successful.
</ResponseField>

<ResponseField name="message" type="string" required>
  Success message confirming the agent voice was updated.
</ResponseField>

<ResponseField name="data" type="object" required>
  The updated agent object with new voice settings.

  <Expandable title="Voice Object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the voice.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Name of the voice.
    </ResponseField>

    <ResponseField name="label" type="string" required>
      Display label for the voice.
    </ResponseField>

    <ResponseField name="stability" type="number">
      Voice stability setting (0.0 to 1.0).
    </ResponseField>

    <ResponseField name="similarity_boost" type="number">
      Voice similarity setting (0.0 to 1.0).
    </ResponseField>

    <ResponseField name="ambient_background" type="string">
      Ambient background setting.
    </ResponseField>

    <ResponseField name="template" type="object">
      Voice template information.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

### Validation Error (422)

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "voice_id": [
        "The voice id field is required."
      ],
      "language": [
        "The language field is required."
      ],
      "conversation_speed": [
        "The conversation speed must be greater than 1 and less than 2."
      ],
      "who_speaks_first": [
        "The selected who speaks first is invalid."
      ],
      "similarity": [
        "The similarity must be at least 0.5 and less than 1."
      ],
      "stability": [
        "The stability must be at least 0.5 and less than 1."
      ]
    }
  }
  ```
</ResponseExample>

### 404 Not Found

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Agent not found"
  }
  ```
</ResponseExample>

### 401 Unauthorized

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthenticated."
  }
  ```
</ResponseExample>

### 403 Forbidden

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "You are not authorized to perform this action."
  }
  ```
</ResponseExample>

## Error codes

| Code               | Description                                        | HTTP Status |
| ------------------ | -------------------------------------------------- | ----------- |
| `AGENT_NOT_FOUND`  | Specified agent does not exist                     | 404         |
| `INVALID_TOKEN`    | Authentication token is invalid or missing         | 401         |
| `UNAUTHORIZED`     | User does not have permission to update this agent | 403         |
| `VOICE_NOT_FOUND`  | Specified voice template does not exist            | 404         |
| `VALIDATION_ERROR` | Request data validation failed                     | 422         |

## Important notes

<Info>
  **Agent status will be set to draft.** After updating the agent's voice, the agent will be automatically set to "draft" status and will need to be published again to become active.
</Info>

<Info>
  **Voice settings affect call quality.** Higher stability values (closer to 1.0) provide more consistent voice output, while higher similarity values (closer to 1.0) enhance voice characteristics.
</Info>

## Related endpoints

* **Get Agent**: `GET /api/v1/agents/{agent_id}`
* **Update Agent Knowledge**: `PUT /api/v1/agents/{agent_id}/knowledge`
* **Update Agent Calling Settings**: `PUT /api/v1/agents/{agent_id}/calling`
* **Publish Agent**: `POST /api/v1/agents/{agent_id}/publish`
* **List Agents**: `GET /api/v1/agents`