# 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 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);
{
"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": [.]
}
}
Agents
Update Agent Voice
Update an agent’s voice settings and configuration
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
}'
// 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);
{
"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": [.]
}
}
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
string
required
The unique identifier of the voice agent to update.
Request headers
string
required
Bearer token for authentication. Format:
Bearer talq_your_environment_token_herestring
required
Must be set to
application/jsonRequest body
string
required
Voice template ID. Use List Voice Templates to retrieve available IDs.
number
required
Conversation playback speed multiplier. Range: greater than
1, less than 2.string
required
Who speaks first. Options:
agent, user.string
Ambient background sound for the conversation (e.g.,
office, cafe, quiet). Optional.number
Volume of the ambient background sound. Range:
0 (muted) to 2 (loud). Default: 1.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.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.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 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);
# 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"
}'
// 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);
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
boolean
required
Indicates if the operation was successful.
string
required
Success message confirming the agent voice was updated.
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
| 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
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.
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
Was this page helpful?