Skip to main content
The agent update system allows you to update existing agents with comprehensive settings. You can update basic details, configuration, knowledge base, calling numbers, denied words, dispositions, guardrails, and metadata. Updates support partial modifications - only the fields you provide will be updated, while others remain unchanged.

​
API Endpoint

Endpoint: POST /api/agent/createagentorupdate Content-Type: multipart/form-data Authentication: Required (Token header: token or api_access_token)

​
Request Structure

The endpoint accepts a multipart/form-data request with the following structure. Include agent_id in basic_details to perform an update: 
{
  "basic_details": {
    "agent_id": 123,                    // Required for updates
    "agent_name": "Updated Name",
    "description": "Updated description",
    "category": 1,
    "purpose": 1,
    "agent_type": 1,                    // 1=Voice, 2=Chat, 3=Telephony, 4=General
    "chatbot_name": "Updated Bot",
    "chatbot_welcome_message": "Welcome!",
    "chatbot_image": "image_url",       // Can be uploaded as file
    "agent_privacy": 0,                 // 0=Private, 1=Public
    "agent_prompt": "Updated prompt...",
    "voice_id": "KYiVPerWcenyBTIvWbfY",
    "voice_provider": 1,
    "transcriber_provider": 2,
    "transcriber_language": "en",
    "tone": "professional",
    "style": "conversational",
    "instruction_sensitivity": "medium"
  },
  "configuration": {
    "agent_id": 123,                    // Required
    "context_awareness": true,
    "memory_recall": true,
    "sentiment_analysis": true,
    "interruption_handling": true,
    "agent_terminate_instruction": "...",
    "agent_terminate_messages": "..."
  },
  "knowledge_base": {
    "agent_id": 123,                    // Required
    "tools": [
      { "id": 1, "isEnabled": true }
    ],
    "sub_agents": [
      { "id": 2, "isEnabled": true }
    ],
    "text_knowledge_bases": [
      { "name": "KB1", "content": "..." }
    ]
  },
  "phone_numbers": ["+1234567890"],
  "denials": {
    "agent_id": 123,
    "denied_words": ["word1", "word2"],
    "denied_topics": ["topic1", "topic2"]
  },
  "dispositions_config": {
    "dispositions": [...]
  },
  "guardrails": {
    "agent_id": 123,
    ...
  },
  "metadata_config": {
    "metadata_input": ["field1", "field2"],
    "metadata_output": ["field1", "field2"]
  }
}
File Uploads:
  • basic_details[chatbot_image] - Chatbot image file (replaces existing)
  • Knowledge base files (PDF, DOC, DOCX, XLSX, CSV) - Up to 3 files, max 10MB each

​
cURL Example

curl -X POST "https://your-api-domain.com/api/agent/createagentorupdate" \
  -H "token: YOUR_AUTH_TOKEN" \
  -F "basic_details[agent_id]=123" \
  -F "basic_details[agent_name]=Updated Agent Name" \
  -F "basic_details[description]=Updated description" \
  -F "basic_details[category]=1" \
  -F "basic_details[purpose]=1" \
  -F "basic_details[agent_type]=1" \
  -F "basic_details[chatbot_name]=Updated Bot" \
  -F "basic_details[chatbot_welcome_message]=Welcome! How can I help you?" \
  -F "basic_details[chatbot_image]=@/path/to/image.png" \
  -F "basic_details[agent_privacy]=0" \
  -F "basic_details[agent_prompt]=Updated agent prompt" \
  -F "basic_details[voice_id]=KYiVPerWcenyBTIvWbfY" \
  -F "basic_details[voice_provider]=1" \
  -F "basic_details[transcriber_provider]=2" \
  -F "basic_details[transcriber_language]=en" \
  -F "basic_details[tone]=professional" \
  -F "basic_details[style]=conversational" \
  -F "basic_details[instruction_sensitivity]=medium" \
  -F "configuration[agent_id]=123" \
  -F "configuration[context_awareness]=true" \
  -F "configuration[memory_recall]=true" \
  -F "configuration[sentiment_analysis]=true" \
  -F "configuration[interruption_handling]=true" \
  -F "configuration[agent_terminate_instruction]=End conversation politely" \
  -F "configuration[agent_terminate_messages]=Thank you for contacting us" \
  -F "knowledge_base[agent_id]=123" \
  -F "knowledge_base[tools][0][id]=1" \
  -F "knowledge_base[tools][0][isEnabled]=true" \
  -F "knowledge_base[sub_agents][0][id]=2" \
  -F "knowledge_base[sub_agents][0][isEnabled]=true" \
  -F "knowledge_base[text_knowledge_bases][0][name]=KB1" \
  -F "knowledge_base[text_knowledge_bases][0][content]=Updated knowledge base content" \
  -F "FILE_KNOWLEDGE_BASES=@/path/to/document.pdf" \
  -F "phone_numbers[]=+1234567890" \
  -F "phone_numbers[]=+0987654321" \
  -F "denials[agent_id]=123" \
  -F "denials[denied_words][]=word1" \
  -F "denials[denied_words][]=word2" \
  -F "denials[denied_topics][]=topic1" \
  -F "denials[denied_topics][]=topic2" \
  -F "metadata_config[metadata_input][]=field1" \
  -F "metadata_config[metadata_input][]=field2" \
  -F "metadata_config[metadata_output][]=field1" \
  -F "metadata_config[metadata_output][]=field2"
Note: Remove any fields you don’t need to update. Only basic_details[agent_id] is required. All other fields are optional and only provided fields will be updated.

​
Response

​
Success Response

Status Code: 200 OK 
{
  "message": "Agent updated successfully",
  "data": {
    "agent_id": 123
  }
}

​
Error Responses

​
422 - Validation Error

Status Code: 422 Unprocessable Entity 
{
  "error": true,
  "code": 422,
  "message": "Agent ID is missing",
  "data": {}
}
Common Error Messages:
  • "Agent ID is missing" - Required field agent_id is missing in basic_details
  • "Agent ID is invalid" - Invalid agent ID format
  • "Agent not found" - Agent with provided ID does not exist
  • "Basic details are required" - basic_details object is missing

​
401 - Authentication Error

Status Code: 401 Unauthorized 
{
  "error": true,
  "code": 401,
  "message": "Invalid Auth Key or Session Expired",
  "data": {}
}

​
500 - Server Error

Status Code: 500 Internal Server Error 
{
  "error": true,
  "code": 500,
  "message": "Internal server error",
  "data": {}
}

​
Error Codes

Status CodeError CodeDescription
200-Success
401AUTH_REQUIREDAuthentication required - Missing or invalid token
401AUTH_INVALIDInvalid authentication token or session expired
422VALIDATION_ERRORValidation failed - Check required fields and data format
422MISSING_FIELDRequired field missing
422INVALID_FORMATInvalid data format or type
422AGENT_NOT_FOUNDAgent with provided ID does not exist
500SERVER_ERRORInternal server error

​
Update Behavior

​
Partial Updates

  • Only fields you provide will be updated
  • Fields not included in the request remain unchanged
  • You can update specific sections without affecting others
Example: 
// Update only agent name
{
  "basic_details": {
    "agent_id": 123,
    "agent_name": "New Name"
  }
}
// All other fields remain unchanged

​
Behavior Fields Merging

When updating behavior fields (tone, style, instruction_sensitivity):
  • If you provide only one field, the others remain unchanged
  • Example: Updating only tone preserves existing style and instruction_sensitivity

​
Knowledge Base Updates

  • New files are added to existing knowledge base
  • Existing files remain unless explicitly removed
  • Tools and sub-agents can be enabled/disabled
  • Agent training status is reset when knowledge base is updated

​
Tools and Sub-agents

  • Existing tools/sub-agents are matched by ID
  • You can enable/disable existing tools/sub-agents
  • New tools/sub-agents can be added
  • Tools not included in the update remain unchanged

​
Additional Update Endpoints

​
Update Agent Status

Endpoint: POST /api/agent/status Request: 
{
  "agent_id": 123,
  "status": 1  // 1=Published, 2=Deleted, 3=Unpublished
}
Response: 
{
  "message": "Agent Published Successfully",
  "data": {
    "id": 123,
    "name": "Agent Name",
    "status": 1
  }
}
Status Values:
  • 1 (Published): Agent is active and available for use
  • 2 (Deleted): Agent is soft-deleted
  • 3 (Unpublished): Agent is inactive but not deleted
Note: Publishing a Telephony agent (type 3) requires at least one phone number to be assigned.

​
Update Knowledge Base Status

Endpoint: POST /api/agent/updateKnowledgeBaseStatus Request: 
{
  "knowledge_base_id": 456,
  "status": 1  // 1=Active, 2=Deleted
}
Response: 
{
  "message": "Knowledge base status updated successfully",
  "data": {
    "id": 456,
    "name": "Knowledge Base Name",
    "status": 1
  }
}

​
Update Denied Word and Disposition Status

Endpoint: POST /api/agent/updateDeniedWordAndDisposition Request: 
{
  "agent_id": 123,
  "denied_word_id": 789,      // Optional: for denied word update
  "disposition_id": 101,      // Optional: for disposition update
  "status": 1                 // 1=Active, 2=Deleted
}
Response: 
{
  "message": "Denied word status updated successfully",
  "data": {
    "type": "denied_word",
    "id": 789,
    "word_topic": "word",
    "status": 1
  }
}

​
Important Notes

  • agent_id is required in basic_details for all updates
  • All configuration sections are optional - only include what you want to update
  • Partial updates are supported - only provided fields are updated
  • File uploads replace existing files (chatbot image) or add new files (knowledge base)
  • Knowledge base updates reset agent training status
  • Updates are atomic - if any part fails, all changes are rolled back
  • All updates are tracked in change history for audit purposes