Agents

Update Agent

Updates the specified draft version of an agent. version_number is required.

Managing functions via this endpoint:

  • Pass agent_functions: [...] to replace the version's functions. The platform end_call function is always kept.
  • Pass agent_functions: [] to remove every function except end_call.
  • Omit agent_functions entirely to leave existing functions untouched.

Post-call analysis LLM:

  • Pass post_call_analysis_llm_id, for example llm_A1B2C3D4E5F6G7, to set the LLM used for post-call field extraction.
  • Pass null to clear it so the workspace default is used.
  • Omit the field to leave it unchanged.
  • It is stored on the version's existing post-call fields: it has no effect when there are none, a replaced post_call_analysis list gets new fields without it, and it is saved before the rest of the request is validated, so a rejected request can still have changed it.

Phone numbers are linked to the agent, not to a version. Manage them with /v1/agents/{agentId}/phone-numbers. Every version uses the agent's numbers, and inbound calls run on the latest published version.

While a batch is running on this agent, the request returns 409 Conflict with code AGENT_HAS_RUNNING_BATCH when it would change a published version in place (runtime fields; version_title and folder_id can still change) or change timezone or pipeline_type. Drafts stay editable and can be published. The running batch keeps dialing the version it was created with.

A published version cannot be edited. Runtime changes are blocked while a batch runs on the agent; edit and publish a new draft instead.

Null is ignored for end_call_on_hold_sec, language_default_message, version_title, reminder_message_content, llm_fallback_model and llm_fallback_delay_ms: the stored value is kept.

patch/v1/agents/{id}

Request

  • Base URL: https://api.dialnexa.com
  • URL: https://api.dialnexa.com/v1/agents/{id}
  • Auth: HTTP bearer

Path parameters

idstring required
Example:agent_2g7Xy3tY53gRlp

Agent ID

Request body

background_soundstring

Background sound identifier. When ambient_noise is on, calls play the built-in background track whatever value is set; set it to a value other than none for background_sound_volume to apply.

background_sound_volumenumber

Volume of the background sound (0 to 2). Applied only when ambient_noise is true and background_sound is set to a value other than none.

ambient_noiseboolean

Enable or disable ambient noise playback on the call

responsivenessnumber

Seconds to wait after the caller stops speaking, 0 to 1. Stored on the agent version; not applied to calls.

interruption_sensitivitynumber

Interruption sensitivity level (0 to 1). Stored on the agent version; not applied to calls.

response_eagernessnumber

How eagerly the agent responds (0 to 1). Applied when the transcriber is Sarvam or Deepgram (Nova-2, Nova-3, Flux); Soniox agents ignore it.

denoising_mode'remove_noise' | 'remove_noise_and_speech' nullable

Denoising mode. Only remove_noise turns denoising on; remove_noise_and_speech leaves it off. Web calls run without denoising.

denoise_strengthnumber nullable

Noise suppression strength 0-4 (higher = stronger)

boosted_keywordsstring

Comma-separated list of words or phrases (e.g. "DialNexa, NexaFlow, customer success") used to bias the speech-to-text provider toward recognizing them correctly. This is a recognition bias, not a guarantee: it increases the likelihood of correctly transcribing uncommon names, brands, products, and domain vocabulary. Supported for Deepgram and Soniox transcribers (primary or fallback). Normalized to at most 100 unique terms (case-insensitive, duplicates removed, empty entries dropped) at the configuration boundary; empty/null means no boosted keywords.

boost_dynamic_variablesboolean

When true, each call's dynamic-variable VALUES (from the test-call form or a batch-call CSV lead: names, cities, order IDs) are appended to boosted_keywords for that call, so per-call uncommon words get the same recognition bias. Values are sanitized first (punctuation stripped, over-long entries dropped) and never evict the agent's own configured terms, which always come first. Applies to Deepgram and Soniox only; defaults to false.

reminder_message_intervalnumber

Seconds of silence before a reminder. Zero disables reminders. Keep at least five seconds below end_call_on_silence_sec when enabled.

reminder_message_contentstring nullable

Reminder text spoken after reminder_message_interval seconds of silence, up to 150 characters. When unset, a language-appropriate default is spoken. On update, null (and an empty string) is ignored and the stored value is kept: the update only writes fields that are not null or empty.

transcriber_idstring nullable

ID of the transcriber catalog entry

fallback_stt_enabledboolean

Enable parallel fallback STT for this agent

stt_fallback_transcriber_idstring nullable

Fallback STT transcriber catalog entry

stt_fallback_wait_msnumber nullable

Milliseconds to wait for primary STT after fallback finalizes first

audio_cache_enabledboolean

TTS audio caching for this agent. Only DialNexa can disable it, so sending false returns 403. Omitting this field leaves the current value unchanged.

voicemail_detectionboolean

Indicates whether voicemail detection is enabled

hangup_on_voicemailboolean

Hang up immediately when voicemail is detected instead of leaving a message

voicemail_messagestring

Message spoken when voicemail is detected (only used when hangup_on_voicemail is false). Supports Handlebars template syntax ({{variable}}). Must be valid Handlebars.

end_call_on_silence_secnumber

Seconds of silence after which the call is automatically ended. Accepted range: 15 to 30 seconds. Must be at least 5 seconds above reminder_message_interval when reminders are configured.

end_call_on_hold_secnumber nullable

Seconds to wait during a sustained detected hold before ending a non-IVR call, 10 to 60. On update, null is ignored and the stored value is kept; an empty string fails validation and returns 400.

max_call_duration_secnumber

Maximum call duration in seconds before the call is forcibly ended. Maximum accepted: 3600 seconds for speech-to-speech agents, 5400 seconds for cascaded agents.

ring_duration_secnumber

Ring timeout for outbound Plivo calls in every workspace, default 30 seconds. Numeric input is rounded to a whole second and clamped to 10 through 30: 5 saves as 10, 90 as 30, and 22.6 as 23. Non-numeric input is rejected. Read the saved value after updating. Has no effect on inbound or web calls.

version_numberinteger required

Version number to update, as a whole JSON number. current_version_number and version_number are returned as strings, so convert them before sending. A fractional value matches no version and returns 404.

folder_idstring

ID of the folder this agent belongs to

pipeline_type'Cascaded' | 'Speech_To_Speech'

Pipeline subtype for Single_Prompt_Agent. Cascaded = ASR→LLM→TTS pipeline. Speech_To_Speech = direct speech model.

titlestring

Title of the agent (max 70 characters)

version_titlestring nullable

Version title, 1 to 150 characters. If omitted on create, the first version is titled "Version 0". On update, null is ignored and the stored value is kept; an empty string fails validation and returns 400.

descriptionstring

Description of the agent

timezonestring

Timezone for the agent

system_prompt_textstring

Static system instructions. Template variables such as {{customer_name}} are rejected with 400; use prompt_text for dynamic content.

language_idstring

ID of the language the agent speaks

secondary_language_idsstring[]

Up to three additional language IDs in priority order. The chosen voice must support them. Send an empty array on update to clear.

language_default_messagestring nullable

Optional message for an unsupported caller language, up to 500 characters, spoken in the primary language voice. On update, null (and an empty string) is ignored and the stored value is kept: the update only writes fields that are not null or empty.

llm_idstring

ID of the LLM associated with the agent

llm_temperaturenumber

LLM temperature from 0 to 2. Values outside this range return 400. Not applied to Speech-to-Speech agents.

voice_idstring

ID of the voice the agent speaks with. Use GET /v1/voices to browse available voices.

prompt_textstring

Main instructions for the agent. Supports Handlebars template syntax ({{variable}}) for dynamic content. Must be valid Handlebars: malformed syntax causes errors at call time.

ivr_menuobject

IVR menu tree for IVR_Agent type: {entry_node, nodes{...}} with per-node prompt text + digit->node edges. Prompt audio is rendered + cached at publish.

welcome_messagestring

Opening message spoken by the agent at the start of the call. Supports Handlebars template syntax ({{variable}}). Must be valid Handlebars: malformed syntax causes errors at call time.

knowledge_base_idsstring[]

IDs of the knowledge bases attached to this agent version

kb_max_chunksinteger

Maximum number of RAG chunks to fetch (1 to 10)

kb_min_scorenumber

Minimum similarity score threshold for RAG results (0 to 1)

is_publishedboolean

Whether this version is published

default_dynamic_variablesobject

Default values for dynamic variables used in Handlebars templates. For call-transfer flows, the reserved key agent_transfer_destinations accepts a pipe-separated list of phone numbers (maximum 7). Each number must use a supported country code: US (+1) or India (+91), followed by exactly 10 digits (e.g. +11234567890|+919876543210).

fallback_llm_enabledboolean

Enable fallback LLM for this agent

llm_fallback_delay_msinteger nullable

Milliseconds to wait before triggering the fallback LLM, a whole number of 0 or more. On update, null is ignored and the stored value is kept; an empty string fails validation and returns 400.

llm_fallback_modelstring nullable

ID of the LLM to use as fallback. On update, null (and an empty string) is ignored and the stored value is kept: the update only writes fields that are not null or empty.

predictive_preprocessing_enabledboolean

Enable predictive preprocessing for this agent version. Not applied to Conversational Flow or Speech-to-Speech agents, or to web calls.

voice_model_idstring

Speech synthesis model for the selected voice. Each voice is tied to a specific provider, and only that provider's models are valid: submitting a model from a different provider will return 400. In most cases this field can be omitted; the recommended model for the chosen voice is applied automatically. For ElevenLabs voices, the supported model is eleven_flash_v2_5. To find supported models for a specific voice, call GET /v1/voices/{voice_id}/voice-models.

voice_speednumber

Voice speed from 0.25 to 4. Values outside this range return 400. Soniox voices clamp it to 0.7 to 1.3. Speech-to-Speech agents apply it on OpenAI Realtime models only; Gemini Live ignores it.

speech_to_speech_english_accent'indian' | 'british' | 'american'

Accent of the agent's English on Speech-to-Speech calls, for the whole call: indian (default), british or american.

voice_temperaturenumber

Voice temperature from 0 to 2. Values outside this range return 400. Applied by ElevenLabs and Smallest voices only.

voice_volumenumber

Voice volume from -10 to 10. Values outside this range return 400. Applied by Cartesia voices (a negative value plays as 1, maximum 2), Sarvam voices (below 0.1 plays as 1, maximum 3) and Speech-to-Speech agents; other providers ignore it. New agents default to -0.363.

voice_pitchnumber

Voice pitch from -20 to 20. Values outside this range return 400. Applied by Sarvam voices only.

agent_identitystring

Agent identity (required for Conversational_Flow_Agent type on update)

agent_backgroundstring

Agent background (required for Conversational_Flow_Agent type on update)

post_call_analysis_llm_idstring nullable

LLM used for post-call field extraction. Accepts a prefixed ID (for example llm_A1B2C3D4E5F6G7) or a raw ID; null clears it so the default extraction model (gpt-4o-mini) is used. It is stored on the version's existing post-call fields, so it has no effect when the version has none, and a replaced post_call_analysis list creates new fields without it, so they use the default extraction model. It is saved before the rest of the update is validated, so a request that is then rejected (400, 403 or 409) can still have changed it.

Example request

{
  "reminder_message_interval": 10,
  "voicemail_detection": true,
  "voicemail_message": "Hi, please call us back at your convenience.",
  "end_call_on_silence_sec": 20,
  "end_call_on_hold_sec": 20,
  "max_call_duration_sec": 600,
  "ring_duration_sec": 30,
  "version_number": 1,
  "folder_id": "f5k2m8x1q9w3zp",
  "pipeline_type": "Cascaded",
  "title": "Customer Support Agent",
  "version_title": "Version 1.1",
  "description": "This agent handles customer support inquiries",
  "timezone": "Asia/Kolkata",
  "system_prompt_text": "You are a helpful customer support agent named Sarah.",
  "language_id": "lang_en_in",
  "llm_id": "llm_A1B2C3D4E5F6G7",
  "llm_temperature": 1,
  "voice_id": "voice_abc123",
  "prompt_text": "Hello, how can I assist you today?",
  "welcome_message": "Welcome to our service!",
  "knowledge_base_ids": [
    "kb_abc123",
    "kb_def456"
  ],
  "kb_max_chunks": 5,
  "kb_min_score": 0.5,
  "default_dynamic_variables": {
    "firstName": "John",
    "lastName": "Doe",
    "courseType": "Math"
  },
  "llm_fallback_delay_ms": 200,
  "llm_fallback_model": "llm_A1B2C3D4E5F6G7",
  "voice_model_id": "vm4k2p9x7q1z3r",
  "voice_speed": 1,
  "voice_temperature": 1,
  "agent_identity": "You are a helpful customer support agent named Sarah.",
  "agent_background": "You have 5 years of experience in customer support and specialize in helping customers with technical issues.",
  "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7",
  "pronunciations": [
    {
      "original_word": "Nexa",
      "pronunciation_format": "Nek-sa",
      "phonetic_pronunciation": "Nek-sa"
    }
  ]
}

Response

Agent updated successfully.

successtrue required
errorfalse required
statusCodeinteger required
messagestring required
timestampstring date-time required

Example response

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "id": "agent_2g7Xy3tY53gRlp",
    "current_version_number": "3",
    "current_version": {
      "version_number": "1",
      "postcall_analysis": [
        {
          "llm_id": "llm_A1B2C3D4E5F6G7"
        }
      ]
    },
    "versions": [
      {
        "version_number": "1",
        "postcall_analysis": [
          {
            "llm_id": "llm_A1B2C3D4E5F6G7"
          }
        ]
      }
    ],
    "organization_id": "o14XKPP84rt22g",
    "inbound_phone_numbers": [
      {
        "id": "phn_abc123",
        "phone_number": "9876543210",
        "country_iso": "91"
      }
    ],
    "outbound_phone_numbers": [
      {
        "id": "phn_abc123",
        "phone_number": "9876543210",
        "country_iso": "91"
      }
    ],
    "running_batches": [
      {
        "id": "batch_2g7Xy3tY53gRlp"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.