Skip to main content
PUT
/
api
/
v1
/
agents
/
{agent_id}
/
voice
# 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
  }'
{
  "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": [...]
  }
}

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 configuration including voice template, language, conversation speed, and other voice-related settings.

Endpoint

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

Path Parameters

agent
string
required
The unique identifier of the voice agent to update. You can find this in your dashboard under Voice Agents.

Request Headers

Authorization
string
required
Bearer token for authentication. Format: Bearer talq_your_environment_token_here
Content-Type
string
required
Must be set to application/json

Request Body

voice_id
string
required
Voice template ID. Use List Voice Templates to retrieve available IDs.
conversation_speed
number
required
Conversation playback speed multiplier. Range: greater than 1, less than 2.
who_speaks_first
string
required
Who speaks first. Options: agent, user.
ambient_background
string
Ambient background sound for the conversation (e.g., office, cafe, quiet). Optional.
ambient_volume
number
Volume of the ambient background sound. Range: 0 (muted) to 2 (loud). Default: 1.
language
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.
similarity
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.
stability
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.

Example Requests

# 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
  }'
# 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"
  }'

Response

Success Response (200 OK)

{
  "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": [...]
  }
}

Response Fields

success
boolean
required
Indicates if the operation was successful.
message
string
required
Success message confirming the agent voice was updated.
data
object
required
The updated agent object with new voice settings.

Error Responses

Validation Error (422)

{
  "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."
    ]
  }
}

404 Not Found

{
  "success": false,
  "message": "Agent not found"
}

401 Unauthorized

{
  "success": false,
  "message": "Unauthenticated."
}

403 Forbidden

{
  "success": false,
  "message": "You are not authorized to perform this action."
}

Error Codes

CodeDescriptionHTTP Status
AGENT_NOT_FOUNDSpecified agent does not exist404
INVALID_TOKENAuthentication token is invalid or missing401
UNAUTHORIZEDUser does not have permission to update this agent403
VOICE_NOT_FOUNDSpecified voice template does not exist404
VALIDATION_ERRORRequest data validation failed422

Important Notes

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

Best Practices

  1. Test voice changes - Always test voice updates before publishing
  2. Balance stability and similarity - Higher stability for professional calls, higher similarity for personal touch
  3. Consider conversation speed - Faster speeds for quick interactions, slower for complex topics
  4. Match language to voice - Ensure the voice template supports the specified language
  5. Set appropriate ambient background - Use “office” for business calls, “quiet” for personal calls
  • 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