Skip to main content
PUT
/
api
/
v1
/
agents
/
{agent_id}
/
knowledge
# Request 1: Update basic knowledge settings
curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated agent description with more details",
    "initial_message": "Hello! Welcome to our support line. How may I assist you today?",
    "interrupt_sensitivity": "high",
    "ask_if_human_present_on_idle": true,
    "llm_temperature": 0.8,
    "initial_message_delay": 2
  }'
{
  "success": true,
  "message": "Agent knowledge updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "SupportBot",
    "label": "Customer Support Agent",
    "description": "Updated agent description with more details",
    "language": "en-US",
    "voice": {...},
    "initial_message": "Hello! Welcome to our support line. How may I assist you today?",
    "interrupt_sensitivity": "high",
    "conversation_speed": 1.0,
    "initial_message_delay": 2,
    "ask_if_human_present_on_idle": true,
    "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:35: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 Knowledge

Update an agent’s knowledge base, conversation behavior, and interaction settings. This endpoint allows you to modify the agent’s description, initial message, interrupt sensitivity, and other behavioral parameters.

Endpoint

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

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

description
string
required
Agent description (min 5 characters)
initial_message
string
Initial message (min 5 characters, max 255 characters)
interrupt_sensitivity
string
required
Interrupt sensitivity level. Options: low, medium, high
ask_if_human_present_on_idle
boolean
required
Whether to ask if human is present when idle
llm_temperature
number
required
LLM temperature (min: 0, max: 2)
initial_message_delay
integer
required
Initial message delay (min: 0, max: 60)

Example Requests

# Request 1: Update basic knowledge settings
curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated agent description with more details",
    "initial_message": "Hello! Welcome to our support line. How may I assist you today?",
    "interrupt_sensitivity": "high",
    "ask_if_human_present_on_idle": true,
    "llm_temperature": 0.8,
    "initial_message_delay": 2
  }'
# Request 2: Update for sales-focused agent
curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Sales agent focused on product demonstrations and lead qualification",
    "initial_message": "Hi! I am calling to introduce our new product line. Do you have 5 minutes to learn about how it can benefit your business?",
    "interrupt_sensitivity": "medium",
    "ask_if_human_present_on_idle": false,
    "llm_temperature": 0.9,
    "initial_message_delay": 1
  }'

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Agent knowledge updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "SupportBot",
    "label": "Customer Support Agent",
    "description": "Updated agent description with more details",
    "language": "en-US",
    "voice": {...},
    "initial_message": "Hello! Welcome to our support line. How may I assist you today?",
    "interrupt_sensitivity": "high",
    "conversation_speed": 1.0,
    "initial_message_delay": 2,
    "ask_if_human_present_on_idle": true,
    "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:35:00Z",
    "trainings": [...],
    "actions": [...],
    "phone_numbers": [...]
  }
}

Response Fields

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

Error Responses

Validation Error (422)

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "description": [
      "The description field is required."
    ],
    "interrupt_sensitivity": [
      "The selected interrupt sensitivity is invalid."
    ],
    "llm_temperature": [
      "The llm temperature must be between 0 and 2."
    ],
    "initial_message_delay": [
      "The initial message delay must be between 0 and 60."
    ]
  }
}

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
VALIDATION_ERRORRequest data validation failed422

Important Notes

Agent status will be set to draft. After updating the agent’s knowledge, the agent will be automatically set to “draft” status and will need to be published again to become active.
LLM Temperature affects creativity. Higher values (closer to 2) make responses more creative and varied, while lower values (closer to 0) make responses more focused and consistent.

Best Practices

  1. Test changes in draft mode - Always test knowledge updates before publishing
  2. Use clear descriptions - Provide detailed descriptions to help the agent understand its role
  3. Optimize interrupt sensitivity - Use “high” for support agents, “medium” for sales, “low” for informational
  4. Set appropriate delays - Use longer delays for outbound calls, shorter for inbound
  5. Monitor LLM temperature - Adjust based on whether you need consistent or creative responses
  • Get Agent: GET /api/v1/agents/{agent_id}
  • Update Agent Voice: PUT /api/v1/agents/{agent_id}/voice
  • 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