> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnani.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Agent
> Update an existing agent's configuration — all fields are optional
## Overview
Update an existing voice agent's configuration. All request body fields are optional — only the fields you include are modified. Unspecified fields retain their current values. This endpoint is the primary way to configure an agent's ASR, LLM, TTS, language settings, advance settings, and integrations.
## Required Permission
`agents`
## Path Parameters
| Name | Type | Required | Description |
| ------- | ------ | -------- | ------------------------ |
| `botId` | string | Yes | Unique agent identifier. |
## Top-Level Request Body Fields
| Field | Type | Description |
| ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `botName` | string | New display name for the agent. |
| `description` | string | Updated agent description. |
| `greetingMessage` | string | Opening message spoken at the start of each call. |
| `endMessage` | string | Closing message spoken before the call ends. |
| `systemPrompt` | string | LLM system prompt. Supports Jinja2 template variables (e.g. `{{ customer_name }}`). |
| `hasDynamicGreeting` | boolean | Enable fetching the greeting from an external API at call start. |
| `dynamicInitialMessageConfig` | object | `{ hasHeaders, method, url, headers[{ id, key, value }] }` — webhook config for dynamic greeting. |
| `botDetails` | object | `{ language: string[] (max 3), region, timeZone, description }` |
| `asrParams` | object | `{ provider, model, language }` — the selected model must support all configured languages. |
| `llmParams` | object | `{ provider, model, temperature (0.0–1.0), maxTokens (1–4096) }` |
| `ttsParams` | object | `{ provider, voice, language, ttsRate (0.5–2.0), enableCaching }` |
| `advanceSettings` | object | ASR advance settings. See table below. |
| `languageSwitch` | boolean | Enable automatic language switching mid-call. |
| `explicitLanguageSwitch` | boolean | Use explicit language switch mode (agent asks the caller to confirm). |
| `languageSwitchMode` | string | `'implicit'` or `'explicit'`. Controls how language switch is initiated. |
| `minWordsForLangSwitch` | integer | Minimum words in the non-primary language before switching. Must be >= 1. Default: `2`. |
| `callTransferConfig` | object | `{ description, defaultTransferMessage, details[{ phoneNumber, countryCode, prompt, message }] }` |
| `callTransferConfigStatus` | boolean | Enable or disable call transfer functionality. |
| `preCall` | object | `{ preCallVariableStatus, preCallParams: { primaryVariable, variables[] } }` |
| `enableVoiceMailDetection` | boolean | Enable the voicemail detection feature. |
| `voiceMailDetectionConfig` | object | `{ enabled, maxDetectionRetries (>=1), maxVoicemailMessageWaitTime (>=1), voiceMailResponse, postDetectionActions[] }` |
| `hasPostCallTrigger` | boolean | Enable or disable the post-call webhook. |
| `postCallTriggerAPIConfig` | object | `{ hasHeaders, method ('GET' \| 'POST'), url, headers[{ id, key, value }] }` |
### `advanceSettings` Fields
| Field | Type | Range / Notes |
| ---------------------------------- | --------- | ---------------------------------------------------------------------------------------- |
| `barge` | boolean | Enable or disable caller barge-in. |
| `initialMessageBarge` | boolean | Allow the caller to interrupt the opening greeting. |
| `useDenoiser` | boolean | Apply background noise filtering. |
| `suppressionLevel` | integer | Noise suppression level: 20–100. |
| `enableItnForAsr` | boolean | Apply Inverse Text Normalization to ASR output. |
| `maxSpeechDuration` | number | Maximum utterance duration in seconds: 1–240. |
| `speechInitialSilenceTimeout` | number | Silence threshold before ASR activates: 10–30s (streaming) or 10–60s (others). |
| `endSilenceTimeout` | number | End-of-speech silence in milliseconds. Stored directly. |
| `speechSegmentationSilenceTimeout` | number | Utterance segmentation silence gap: 0.1–5s. **Streaming models only.** |
| `minWordsForBargeIn` | integer | Minimum words before a barge-in registers: 1–5. **Streaming ASR only.** |
| `minTimeToBarge` | number | Minimum elapsed time before barge-in is accepted: 0.1–3s. **Non-streaming ASR only.** |
| `asrPreemptive` | boolean | Enable Fast Streaming mode. **Fast REST ASR models only.** |
| `enableDtmf` | boolean | Accept DTMF keypad input during the call. |
| `phraseConfig.phrase` | string\[] | Custom vocabulary hint phrases. Maximum 100 entries. **Vocabulary-capable models only.** |
| `phraseConfig.phraseWeight` | number | Recognition bias weight for custom vocabulary: 0.0–2.0. |
Sending an `advanceSettings` field that is not supported by the current ASR model returns HTTP 400. Use **Get Transcriber Config** to verify model compatibility before updating.
## ASR Model Compatibility — `advanceSettings` Reference
Each `advanceSettings` field is valid only for specific ASR model types. Sending an incompatible field returns HTTP 400.
| Setting | Valid For | Supported Models |
| --------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `minWordsForBargeIn` | Streaming only | `gnani_asr`, `microsoft_streaming`, `elevenlabs_streaming`, `gladia_streaming`, `gemini-2.5-flash-native-audio-preview-09-2025` |
| `minTimeToBarge` | Non-streaming (REST) only | `microsoft_rest`, `elevenlabs_rest` |
| `speechSegmentationSilenceTimeout` | Streaming + select REST | `microsoft_streaming`, `elevenlabs_streaming`, `microsoft_rest` |
| `phraseConfig.phrase` | Vocabulary-capable models only | `microsoft_streaming`, `gnani_asr`, `elevenlabs_streaming`, `elevenlabs_rest` |
| `asrPreemptive` | Fast REST models only | `elevenlabs_rest` |
| `speechInitialSilenceTimeout` (max 30s) | Streaming + select REST | `microsoft_streaming`, `elevenlabs_streaming`, `microsoft_rest` |
| `speechInitialSilenceTimeout` (max 60s) | Other models | `gnani_asr`, `gladia_streaming`, `gemini-2.5-flash-native-audio-preview-09-2025` |
| `barge`, `useDenoiser`, `enableDtmf`, `maxSpeechDuration` | All models | Any |
## Example cURL
### Update Messages
```bash theme={null}
curl -X PUT "https://api.inya.ai/platform/v1/agents/fb79920229d144608ebf665a10e50275" \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"greetingMessage": "Hello, how can I help you today?",
"endMessage": "Thank you for calling. Have a great day!"
}'
```
### Full Configuration Update
```bash theme={null}
curl -X PUT "https://api.inya.ai/platform/v1/agents/fb79920229d144608ebf665a10e50275" \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"botName": "Support Agent v2",
"description": "Handles inbound support and billing queries.",
"greetingMessage": "Hello, how can I help you today?",
"endMessage": "Thank you for calling. Have a great day!",
"systemPrompt": "You are a helpful support agent for {{ company_name }}.",
"hasDynamicGreeting": false,
"botDetails": {
"language": ["en-IN", "hi-IN"],
"region": "asia",
"timeZone": "Asia/Kolkata"
},
"asrParams": {
"provider": "gnani",
"model": "gnani_asr",
"language": "en-IN"
},
"llmParams": {
"provider": "gnani",
"model": "Pampa Go",
"temperature": 0.7,
"maxTokens": 400
},
"ttsParams": {
"provider": "gnani",
"voice": "Pranav",
"language": "en-IN",
"ttsRate": 1.2,
"enableCaching": true
},
"advanceSettings": {
"barge": true,
"initialMessageBarge": false,
"useDenoiser": true,
"suppressionLevel": 80,
"enableItnForAsr": false,
"maxSpeechDuration": 15,
"speechInitialSilenceTimeout": 10.0,
"endSilenceTimeout": 800,
"enableDtmf": false,
"phraseConfig": {
"phrase": ["billing", "refund", "account"],
"phraseWeight": 1.0
}
},
"languageSwitch": true,
"languageSwitchMode": "explicit",
"minWordsForLangSwitch": 2,
"preCall": {
"preCallVariableStatus": true,
"preCallParams": {
"primaryVariable": "customer_name",
"variables": [
{ "variable": "customer_name", "sampleValue": "Alice", "description": "Customer full name" },
{ "variable": "account_id", "sampleValue": "ACC123", "description": "Customer account ID" }
]
}
},
"enableVoiceMailDetection": true,
"voiceMailDetectionConfig": {
"enabled": true,
"maxDetectionRetries": 2,
"maxVoicemailMessageWaitTime": 3,
"voiceMailResponse": "We tried to reach you. Please call us back.",
"postDetectionActions": []
},
"callTransferConfig": {
"description": "Transfer to live support agent",
"defaultTransferMessage": "Please hold. Transferring you now.",
"details": [
{ "phoneNumber": "9876500000", "countryCode": "+91", "prompt": "Transfer", "message": "Hold on" }
]
},
"callTransferConfigStatus": false,
"hasPostCallTrigger": true,
"postCallTriggerAPIConfig": {
"hasHeaders": false,
"method": "POST",
"url": "https://your-server.example.com/call_status",
"headers": null
}
}'
```
## Response
### Success (200)
```json theme={null}
{
"status": "success",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "Agent updated successfully",
"response": { "botId": "fb79920229d144608ebf665a10e50275" }
}
```
### Error Responses
**400 Bad Request** - Validation error
```json theme={null}
{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "Selected ASR model does not support selected languages. Please check /platform/v1/agents/config/transcriber_config"
}
```
**403 Forbidden** - Insufficient permissions or agent not found
```json theme={null}
{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "QA role does not have permission to create/update agents"
}
```
**403 Forbidden** - Agent does not exist or not accessible
```json theme={null}
{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "User does not have access to this bot"
}
```
**409 Conflict** - Agent name already taken
```json theme={null}
{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "An agent named 'Support Agent v2' already exists in your organization"
}
```
## Configuring a Multilingual Agent
Set `botDetails.language` to an array of up to three language codes. The selected ASR model must support every language in the list — use **Get Transcriber Config** with multiple `language` parameters to identify compatible options. The TTS voice must also support all configured languages — use **Get TTS Config** similarly. LLM models are language-agnostic.
```bash theme={null}
curl -X PUT "https://api.inya.ai/platform/v1/agents/fb79920229d144608ebf665a10e50275" \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"botDetails": { "language": ["en-IN", "hi-IN"] },
"asrParams": {
"provider": "microsoft",
"model": "microsoft_streaming_multilingual",
"language": "en-IN"
},
"ttsParams": {
"provider": "gnani",
"voice": "Nalini",
"language": "en-IN"
},
"languageSwitch": true,
"languageSwitchMode": "explicit",
"minWordsForLangSwitch": 2
}'
```
## Use Cases
* Updating agent messages for seasonal campaigns or new use cases
* Fine-tuning the system prompt based on observed performance
* Switching ASR, LLM, or TTS providers and models
* Enabling advanced features like voicemail detection or call transfer
* Configuring a post-call webhook for CRM updates or analytics pipelines
Always validate your ASR and TTS selections against the **Agent Config API** before updating. This ensures the selected provider/model combination supports all configured languages.
Save the `requestId` from every response. You will need it if you contact Inya support to trace a specific request.
## OpenAPI
````yaml PUT /v1/agents/{botId}
openapi: 3.0.3
info:
title: Platform Agents API
description: API endpoints for creating, managing, and interacting with voice agents
version: 2.1.0
servers:
- url: https://api.inya.ai/platform
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Agents
description: Agent management operations
- name: AgentFAQ
description: Agent FAQ management
- name: AgentCallTriggers
description: Outbound call triggers
- name: ChatSDK
description: Chat Widget configuration
- name: Conversations
description: Conversation logs, statistics, and audio
paths:
/v1/agents/{botId}:
put:
tags:
- Agents
summary: Update agent
description: >-
Update an existing agent's configuration. All request body fields are
optional — only the fields you include are modified.
operationId: updateAgent
parameters:
- $ref: '#/components/parameters/AgentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAgentRequest'
examples:
updateMessages:
summary: Update greeting and end messages
value:
greetingMessage: Welcome! How may I assist you?
endMessage: Thank you for calling. Have a great day!
updatePrompt:
summary: Update system prompt
value:
systemPrompt: >-
You are a professional customer service agent for {{
company_name }}.
fullUpdate:
summary: Full configuration update
value:
botName: Support Agent v2
greetingMessage: Hello, how can I help you today?
llmParams:
provider: gnani
model: Pampa Go
temperature: 0.7
maxTokens: 400
ttsParams:
provider: gnani
voice: Pranav
language: en-IN
ttsRate: 1.2
enableCaching: true
advanceSettings:
barge: true
useDenoiser: true
suppressionLevel: 80
maxSpeechDuration: 15
responses:
'200':
description: Agent updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse'
examples:
success:
value:
status: success
requestId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
message: Agent updated successfully
response:
botId: fb79920229d144608ebf665a10e50275
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/ServerError'
components:
parameters:
AgentId:
name: botId
in: path
required: true
description: Unique identifier of the agent
schema:
type: string
schemas:
UpdateAgentRequest:
type: object
properties:
botName:
type: string
description:
type: string
greetingMessage:
type: string
endMessage:
type: string
systemPrompt:
type: string
description: Supports Jinja2 template variables, e.g. {{ customer_name }}
hasDynamicGreeting:
type: boolean
dynamicInitialMessageConfig:
type: object
properties:
hasHeaders:
type: boolean
method:
type: string
url:
type: string
headers:
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
value:
type: string
botDetails:
type: object
properties:
language:
type: array
items:
type: string
description: Up to 3 language codes
maxItems: 3
region:
type: string
timeZone:
type: string
description:
type: string
asrParams:
$ref: '#/components/schemas/AsrParams'
llmParams:
$ref: '#/components/schemas/LlmParams'
ttsParams:
$ref: '#/components/schemas/TtsParams'
advanceSettings:
$ref: '#/components/schemas/AdvanceSettings'
languageSwitch:
type: boolean
explicitLanguageSwitch:
type: boolean
languageSwitchMode:
type: string
enum:
- implicit
- explicit
minWordsForLangSwitch:
type: integer
minimum: 1
default: 2
callTransferConfig:
type: object
properties:
description:
type: string
defaultTransferMessage:
type: string
details:
type: array
items:
type: object
properties:
phoneNumber:
type: string
countryCode:
type: string
prompt:
type: string
message:
type: string
callTransferConfigStatus:
type: boolean
preCall:
type: object
properties:
preCallVariableStatus:
type: boolean
preCallParams:
type: object
properties:
primaryVariable:
type: string
variables:
type: array
items:
type: object
properties:
variable:
type: string
sampleValue:
type: string
description:
type: string
enableVoiceMailDetection:
type: boolean
voiceMailDetectionConfig:
type: object
properties:
enabled:
type: boolean
maxDetectionRetries:
type: integer
minimum: 1
maxVoicemailMessageWaitTime:
type: integer
minimum: 1
voiceMailResponse:
type: string
postDetectionActions:
type: array
items:
type: object
hasPostCallTrigger:
type: boolean
postCallTriggerAPIConfig:
type: object
properties:
hasHeaders:
type: boolean
method:
type: string
enum:
- GET
- POST
url:
type: string
headers:
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
value:
type: string
StandardResponse:
type: object
properties:
status:
type: string
example: success
requestId:
type: string
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
message:
type: string
response:
type: object
AsrParams:
type: object
properties:
provider:
type: string
example: gnani
model:
type: string
example: gnani_asr
language:
type: string
example: en-IN
LlmParams:
type: object
properties:
provider:
type: string
example: gnani
model:
type: string
example: Pampa Go
temperature:
type: number
minimum: 0
maximum: 1
example: 0.5
maxTokens:
type: integer
minimum: 1
maximum: 4096
example: 300
TtsParams:
type: object
properties:
provider:
type: string
example: gnani
voice:
type: string
example: Pranav
language:
type: string
example: en-IN
ttsRate:
type: number
minimum: 0.5
maximum: 2
example: 1
enableCaching:
type: boolean
example: true
AdvanceSettings:
type: object
properties:
barge:
type: boolean
default: true
initialMessageBarge:
type: boolean
default: false
useDenoiser:
type: boolean
default: true
suppressionLevel:
type: integer
minimum: 20
maximum: 100
default: 80
enableItnForAsr:
type: boolean
default: false
maxSpeechDuration:
type: number
minimum: 1
maximum: 240
default: 30
speechInitialSilenceTimeout:
type: number
description: 10–30s for streaming models, 10–60s for others
default: 10
endSilenceTimeout:
type: number
description: End-of-speech silence in milliseconds
default: 800
speechSegmentationSilenceTimeout:
type: number
minimum: 0.1
maximum: 5
description: Streaming models only
default: 1000
minWordsForBargeIn:
type: integer
minimum: 1
maximum: 5
description: Streaming ASR only
default: 1
minTimeToBarge:
type: number
minimum: 0.1
maximum: 3
description: Non-streaming ASR only
default: 0.1
asrPreemptive:
type: boolean
description: Fast REST ASR models only
default: false
enableDtmf:
type: boolean
default: false
phraseConfig:
type: object
properties:
phrase:
type: array
items:
type: string
maxItems: 100
description: Vocabulary-capable ASR models only
phraseWeight:
type: number
minimum: 0
maximum: 2
default: 0
ErrorResponse:
type: object
properties:
status:
type: string
example: error
requestId:
type: string
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
message:
type: string
responses:
BadRequest:
description: Validation error or malformed request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Permission denied
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Conflict:
description: Resource conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: API key with 'agents' permission
````