Update Agent

PATCH

agents

{id}

curl --request PATCH \
  --url https://api.dialnexa.com/v1/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version_number": 0,
  "title": "Customer Support Agent",
  "llm_id": "llm_A1B2C3D4E5F6G7",
  "fallback_stt_enabled": true,
  "stt_fallback_transcriber_id": "trs_soniox",
  "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7"
}
'

{
  "success": true,
  "error": false,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "id": "agent_2g7Xy3tY53gRlp",
    "folder_id": null,
    "current_version_number": "0",
    "timezone": "Asia/Kolkata",
    "agent_type": "Single_Prompt_Agent",
    "pipeline_type": "Cascaded",
    "webhook_id": null,
    "current_version": {
      "agent_id": "agent_2g7Xy3tY53gRlp",
      "version_number": "0",
      "version_title": "Version 0",
      "title": "Customer Support Agent",
      "is_published": false,
      "language_id": "lang_en_in",
      "voice_id": "voice_abc123",
      "llm_id": "llm_A1B2C3D4E5F6G7",
      "transcriber_id": "trs_deepgram_nova_2",
      "fallback_stt_enabled": true,
      "stt_fallback_transcriber_id": "trs_soniox"
    },
    "versions": [
      {
        "agent_id": "agent_2g7Xy3tY53gRlp",
        "version_number": "0",
        "version_title": "Version 0",
        "title": "Customer Support Agent",
        "is_published": false,
        "language_id": "lang_en_in",
        "voice_id": "voice_abc123",
        "llm_id": "llm_A1B2C3D4E5F6G7",
        "transcriber_id": "trs_deepgram_nova_2",
        "fallback_stt_enabled": true,
        "stt_fallback_transcriber_id": "trs_soniox"
      }
    ],
    "inbound_phone_numbers": [],
    "outbound_phone_numbers": [
      {
        "id": "phn_abc123",
        "phone_number": "9876543210",
        "country_iso": "91",
        "nickname": "Support line",
        "sip_trunk_enabled": false,
        "linked_at": "2026-09-30T06:00:00.000Z"
      }
    ]
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Changes state - verify before retry Update an existing agent. Send only the fields you want to change. The request is scoped to the authenticated organization automatically.

When to use this

Prompt iteration: change prompt_text or system_prompt_text on a draft version while tuning agent behavior.
Rewiring: point the agent at a different voice, LLM, transcriber, or knowledge base without recreating it.
Publishing: set is_published to promote a draft version once it is ready for production traffic.
Fallback configuration: enable LLM or STT fallbacks so calls survive a provider outage (see the sections below).

A 400 Bad Request means a field failed validation; 404 Not Found means the agent or the version does not exist in this workspace. 403 Forbidden means the version is already published (see below) or the request tried to turn off a setting only DialNexa can disable, such as audio caching or predictive preprocessing. See API errors for the standard error format.

Minimal publish request

{
  "version_number": 0,
  "is_published": true
}

A new agent’s first draft is version 0. Read current_version_number from Get Agent Details when publishing a later draft. It is returned as a string, and version_number must be sent as a JSON number, so convert it first: "2" returns 400. Send only the fields you intend to change. The remaining schema groups cover advanced prompt, speech, fallback, analysis, function, and routing settings.

Post-Call Analysis LLM

Use post_call_analysis_llm_id on this endpoint to set or clear the LLM used for post-call field extraction on a draft version.

Request field	Result
`post_call_analysis_llm_id: "llm_A1B2C3D4E5F6G7"`	Uses that LLM for post-call extraction.
`post_call_analysis_llm_id: null`	Clears the override and falls back to the workspace default.
Omit `post_call_analysis_llm_id`	Leaves the existing fields’ LLM unchanged.

The LLM is stored on the version’s existing post-call fields. It has no effect when the version has none, and a post_call_analysis list in the same or a later request creates new fields without it, so they use the workspace default: send the list first, then set the LLM. It is also saved before the rest of the request is validated, so a request that is then rejected with 400, 403, or 409 can still have changed it. Send version_number with the request. A version that is already published returns 403 Forbidden on any further update; edit the agent’s current draft and publish it instead. A request with post_call_analysis_llm_id for a published version that is no longer the current one returns 400 instead (Cannot update post-call analysis for a historical published version. Only the current version can be updated.). Publishing a draft with is_published: true is not affected, because the draft is not yet published.

Publishing And Phone Number Assignment

Phone numbers are not part of an agent version, and this endpoint does not accept phone number fields. Numbers are linked to the agent with Attach Agent Phone Number, and every version uses them. After you publish a draft with is_published: true, inbound calls and workflow calls on the agent’s numbers run on the new version without any reassignment. A batch keeps the version it was created with. While a batch is running on this agent, the request returns 409 Conflict with code AGENT_HAS_RUNNING_BATCH and the running batches in data.batches 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 still be published. Pause the batch or wait for it to finish, or publish a new version instead.

Fallback STT

Use fallback_stt_enabled, stt_fallback_transcriber_id, and stt_fallback_wait_ms to configure fallback transcription. Pick the fallback transcriber ID from List Fallback Transcribers, then pass the selected ID here. The fallback transcriber ID must differ from the effective primary transcriber_id. When the fallback or the languages change, a fallback that cannot serve the agent’s languages is replaced with a compatible one, or fallback is turned off when none fits, so a language-only update can change these fields.

Speech And Model Settings

Use boosted_keywords when a cascaded Deepgram, Soniox or Sarvam agent (for Sarvam a best-effort hint) needs recognition hints for names, products, localities, or other uncommon terms. Send a comma-separated string. Terms can contain letters, numbers, and spaces only, with up to 100 normalized terms, 50 characters per term, and 2,000 total characters. Set boost_dynamic_variables to true to append sanitized test-call or batch-recipient values to those recognition hints at call time. The configured terms keep priority, and existing agents remain opted out until this field is enabled. Predictive preprocessing and audio caching are on by default and only DialNexa can turn them off: sending false for predictive_preprocessing_enabled or audio_cache_enabled returns 403 Forbidden, except when DialNexa has already switched predictive preprocessing off itself because functions are configured or the agent is a Conversational Flow agent. When functions are configured, the primary and fallback LLM must support tool calling; a model that does not returns 400. DialNexa forces predictive preprocessing off for that effective configuration. For an IVR Agent, send ivr_menu only to a draft. Publish the IVR draft through this agent update operation. Do not use a direct version-publish route. Publishing validates the graph and renders every static prompt to cached audio before the version becomes available.

Publish Checks And Voice Tuning

Publishing requires a non-empty universal prompt for Single Prompt agents, a custom welcome message when the agent is set in the dashboard to open with a fixed welcome, valid content in Conversational Flow nodes, and a transcriber compatible with the selected language. A version whose LLM, or enabled fallback LLM, has been retired cannot be published: the request returns 400 with data.code LLM_RETIRED; pick a model from List LLMs and publish again. Drafts can remain incomplete while you edit. Before publishing an IVR, read the target variables and set non-empty fallback_dynamic_variables on each Connect To Agent node. Check IVR references before publishing a target agent, and check changed targets before republishing an IVR. PATCH accepts voice_speed from 0.25 to 4, voice_temperature from 0 to 2, voice_volume from -10 to 10, voice_pitch from -20 to 20, and llm_temperature from 0 to 2. For a recognized cascaded voice provider, saving a changed voice or speed clamps the saved speed: Sarvam 0.3 to 3, Soniox 0.7 to 1.3, and ElevenLabs, Cartesia, or Smallest AI 0.7 to 1.2. Read the saved value after updating. Values outside the API bounds return 400. Not every provider uses every setting: voice_volume is applied by Cartesia and Sarvam voices and by Speech-to-Speech agents, voice_pitch by Sarvam voices, and voice_temperature by ElevenLabs and Smallest AI voices; other providers ignore them. Speech-to-Speech agents apply volume, apply speed on OpenAI Realtime models only, and do not use llm_temperature.

Null Values On Update

The update writes only fields that are present and not null or empty. Sending null for end_call_on_hold_sec, language_default_message, version_title, reminder_message_content, llm_fallback_model, or llm_fallback_delay_ms is ignored: the stored value is kept. An empty string "" is also ignored for language_default_message, reminder_message_content, and llm_fallback_model; for end_call_on_hold_sec, llm_fallback_delay_ms, and version_title it fails validation and returns 400. Fields with explicit clearing behaviour are transcriber_id, knowledge_base_ids, stt_fallback_transcriber_id, stt_fallback_wait_ms, denoising_mode, denoise_strength, and post_call_analysis_llm_id, which accept null.

Call Settings

These call settings are accepted on update as well as on create. Send only the fields you want to change; every other setting on the version keeps its current value.

Field	Description
`max_call_duration_sec`	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.
`end_call_on_silence_sec`	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_sec`	Seconds to wait in a confirmed hold (hold detection) before hanging up, counted from hold confirmation. Accepted range: 10 to 60 seconds. Null is ignored on update.
`ring_duration_sec`	Ring timeout for outbound Plivo calls in seconds. Numeric input is rounded and clamped to 10 through 30.
`voicemail_detection`	Whether voicemail detection is enabled for calls this version handles.
`hangup_on_voicemail`	Hang up immediately when voicemail is detected instead of leaving a message
`voicemail_message`	Message spoken when voicemail is detected (only used when hangup_on_voicemail is false). Supports Handlebars template syntax (`{{variable}}`). Must be valid Handlebars.
`pronunciations`	Optional list of pronunciation overrides. Each item has `original_word` (the word as written), `pronunciation_format` (how the voice should say it) and an optional `phonetic_pronunciation`. Each value is a string of up to 128 characters. Applied by ElevenLabs and Cartesia voices only, and only for items with `phonetic_pronunciation`.

Validation Rules

The update request validates the effective draft configuration before saving.

Field	Rule
`prompt_text`, `welcome_message`, and `voicemail_message`	Must be valid Handlebars template text when they use `{{variable}}` syntax.
`system_prompt_text`	Static instructions only. Template variables return `400`; use `prompt_text` for dynamic values.
`voice_model_id`	Must belong to the same provider as the effective `voice_id`. Omit it when changing voices so DialNexa can apply the recommended model.
`stt_fallback_transcriber_id`	Required when fallback STT is enabled and must differ from the effective primary `transcriber_id`. Sending the same ID for both returns `400 Bad Request`.
`default_dynamic_variables.agent_transfer_destinations`	Conversational Flow Agents only. Supports up to `7` pipe-separated transfer numbers. Each must be US `+1` or India `+91` with exactly `10` digits after the country code. Single Prompt Agent updates that include this key return `400 Bad Request`.
`end_call_on_silence_sec`	Must be `15` to `30` seconds and at least `5` seconds above `reminder_message_interval` when reminders are configured.
`max_call_duration_sec`	Must be `60` to `5,400` seconds for cascaded agents. Speech to Speech agents are capped at `3,600` seconds.
`knowledge_base_ids`	Not accepted for Speech to Speech agents: sending any returns `400` (`Knowledge bases cannot be attached to speech-to-speech agents`).
`version_title`	Maximum 150 characters.
`ivr_menu`	IVR Agents only. Checked when the agent is published: a valid entry node, valid edges, static prompt text, and a published non-IVR target for each agent handoff. A draft accepts any object.
LLM IDs when functions are configured	The primary and enabled fallback models must support tool calling. Check compatibility in the dashboard or MCP catalog; API-key model responses contain only `id`, `name`, and `provider`.
Running batch	Changing a published version in place, `timezone`, or `pipeline_type` returns `409 Conflict` with code `AGENT_HAS_RUNNING_BATCH` while a batch is running on the agent. Publishing a draft is not blocked.

Workspace Model Availability

Choose the primary model from List LLMs and an enabled fallback from List Fallback LLMs using the same workspace key.

Check Prompt Health

Create and update responses include prompt_health for Single Prompt and Speech to Speech agents: status, prompt_tokens, limit_tokens, system_prompt_reserved_tokens, limited_by, and comment. Other types report not_applicable. Counts are estimates, with known dynamic defaults expanded and system instructions reserved. Read prompt size limits before changing models or adding large defaults. The size limit is enforced only when publishing: an update to a draft with an oversized prompt succeeds and reports over_ceiling, and publishing that version returns 400. Reduce the prompt or select a suitable model before publishing. Enabled fallback LLM and STT choices must differ from their primary model or transcriber. An invalid pair returns 400. The automatically provided End Call behavior does not count as a callable tool for predictive preprocessing or model tool-compatibility checks.

Create And Update Agent Field Validation

Both operations validate each item in agent_functions and post_call_analysis before saving. Invalid items return 400 Bad Request.

agent_functions must be an array. Each item requires a supported type. Optional displayName (or display_name) and description must be strings; config must be an object.
Post-call fields require a non-blank, unique field_name and one of TEXT, SELECTOR, BOOLEAN, NUMBER, or DATETIME. Use TEXT instead of STRING and SELECTOR instead of ENUM.
A SELECTOR requires at least one non-blank string choice in additional_fields, normally an array such as ["Resolved", "Escalated"]. display_order, when supplied, must be a non-negative integer.
llm_fallback_delay_ms and reminder_message_interval cannot be negative. A reminder interval of 0 disables reminders.
ring_duration_sec defaults to 30 seconds and applies to outbound Plivo calls in every workspace. Numeric input is rounded and clamped to 10 through 30: 5 saves as 10, 90 as 30, and 22.6 as 23. Non-numeric input returns 400. Read the saved value to verify it.
end_call_on_hold_sec accepts 10 to 60 seconds. New agents use 20 when omitted or null. On update, null is ignored and the stored value is kept. Read End Call on Hold for behavior and testing.

On update, send the complete intended function or post-call list because each supplied list replaces its previous contents. Read the draft back with Get Agent and verify the saved fields before publishing.

Update Primary And Secondary Languages

Agent updates accept secondary_language_ids (up to three IDs) and language_default_message (up to 500 characters). Send [] to clear the secondary languages. null and "" are ignored for the message, so the stored message is kept. Review the saved voice and transcriber compatibility before publishing. On a Speech-to-Speech agent, a request that changes llm_id or secondary_language_ids returns 400 when the version would have secondary languages on a model whose provider is not gemini. See multilingual agent configuration.

Update Agent while batches run

Publishing a draft returns data.running_batches with the ID, title, and pinned version of batches currently running on the agent. Those batches keep their existing version. Check the batch in the dashboard before assuming newly published changes apply to it.

Retired Language Models

GPT-4.1 Nano is retired. Choose current primary, fallback, and post-call extraction models when creating an agent or changing its model selection. A new retired-model selection returns 400 with code LLM_RETIRED; publishing and dialing with a retired primary or enabled fallback are also refused. Read the saved model choices before testing.

Configure Emotion Tags

Set emotion_tags_enabled to true for emotional delivery on Cartesia Sonic 3/3.5 or Soniox TTS v2 voices. It defaults to false on create. Explicitly enabling it for an unsupported voice model returns 400; changing to an unsupported voice turns it off. On update, omission leaves the value unchanged unless that voice change disables it. See Emotion tags for testing guidance.

Configure Contact Memory

Contact memory lets your agents remember earlier calls with the same phone number. Each workspace keeps one memory per contact phone number, and every agent in the workspace shares it. Two fields control it, and both default to false:

Field	What it does
`lead_memory_save_enabled`	After each successful phone call this agent makes or answers, the contact’s memory is updated with what was said, such as decisions, dates, offers and open follow-ups.
`lead_memory_enabled`	When a phone call starts, this agent receives the contact’s memory, so it does not ask for details the contact already gave on an earlier call.

A call is saved when it completes normally and the contact speaks. Voicemail, calls where the contact never speaks, and web calls are not saved, and web calls never use memory. Memory builds from the first call saved after you turn saving on; earlier calls are not added. In the dashboard, both settings are in the agent’s Knowledge Base & Memory section. On update, send either field to change it. An omitted field keeps its current value.

Verify the result

Fetch the agent and confirm the intended version is published. Responses can include additional fields not listed here; you can ignore them. If the update timed out, read the agent before repeating the request, especially when publishing.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string

required

Agent ID

Example:

"agent_2g7Xy3tY53gRlp"

Body

application/json

version_number

integer

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.

Example:

1

background_sound

string

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_volume

number

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.

Required range: 0 <= x <= 2

ambient_noise

boolean

Enable or disable ambient noise playback on the call

responsiveness

number

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

Required range: 0 <= x <= 1

interruption_sensitivity

number

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

Required range: 0 <= x <= 1

response_eagerness

number

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.

Required range: 0 <= x <= 1

listening_backchannel

boolean

Play listening sounds (uh-huh, right) while the caller is talking

Example:

false

listening_backchannel_frequency

number

How often a listening sound plays when possible (0-1)

Required range: 0 <= x <= 1

Example:

0.8

denoising_mode

enum<string> | null

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

Available options:

remove_noise,

remove_noise_and_speech

denoise_strength

number | null

Noise suppression strength 0-4 (higher = stronger)

Required range: 0 <= x <= 4

boosted_keywords

string

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.

Maximum string length: 2000

boost_dynamic_variables

boolean

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_interval

number

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

Required range: x >= 0

Example:

10

reminder_message_content

string | null

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.

Maximum string length: 150

transcriber_id

string | null

ID of the transcriber catalog entry

fallback_stt_enabled

boolean

Enable parallel fallback STT for this agent

stt_fallback_transcriber_id

string | null

Fallback STT transcriber catalog entry

stt_fallback_wait_ms

number | null

Milliseconds to wait for primary STT after fallback finalizes first

Required range: x >= 0

audio_cache_enabled

boolean

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

emotion_tags_enabled

boolean

When true, the agent may write inline emotion tags (e.g. [sad], [excited]) that the voice performs. Supported only on Cartesia Sonic 3 and Soniox TTS v2 voices: turning it on for any other voice returns 400, and switching the voice to an unsupported one turns it off. Defaults to false.

voicemail_detection

boolean

Indicates whether voicemail detection is enabled

Example:

true

hangup_on_voicemail

boolean

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

Example:

false

lead_memory_enabled

boolean

Show the lead's earlier successful calls in this workspace to the agent at the start of its next call with them

Example:

false

lead_memory_save_enabled

boolean

Save what was said on this agent's successful calls to lead memory, so agents in this workspace can use it on later calls with the same lead

Example:

false

voicemail_message

string

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

Example:

"Hi, please call us back at your convenience."

end_call_on_silence_sec

number

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.

Required range: 15 <= x <= 30

Example:

20

end_call_on_hold_sec

number | null

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.

Required range: 10 <= x <= 60

Example:

20

max_call_duration_sec

number

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.

Required range: 60 <= x <= 5400

Example:

600

ring_duration_sec

number

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.

Example:

30

folder_id

string

ID of the folder this agent belongs to

Example:

"f5k2m8x1q9w3zp"

pipeline_type

enum<string>

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

Available options:

Cascaded,

Speech_To_Speech

Example:

"Cascaded"

title

string

Title of the agent (max 70 characters)

Required string length: 1 - 70

Example:

"Customer Support Agent"

version_title

string | null

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.

Required string length: 1 - 150

Example:

"Version 1.1"

description

string

Description of the agent

Example:

"This agent handles customer support inquiries"

timezone

string

Timezone for the agent

Example:

"Asia/Kolkata"

system_prompt_text

string

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

Example:

"You are a helpful customer support agent named Sarah."

language_id

string

ID of the language the agent speaks

Example:

"lang_en_in"

secondary_language_ids

string[]

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

Maximum array length: 3

language_default_message

string | null

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.

Maximum string length: 500

llm_id

string

ID of the LLM associated with the agent

Example:

"llm_A1B2C3D4E5F6G7"

llm_temperature

number

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

Required range: 0 <= x <= 2

Example:

1

voice_id

string

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

Example:

"voice_abc123"

prompt_text

string

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

Example:

"Hello, how can I assist you today?"

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_message

string

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.

Example:

"Welcome to our service!"

knowledge_base_ids

string[]

IDs of the knowledge bases attached to this agent version

Example:

["kb_abc123", "kb_def456"]

kb_max_chunks

integer

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

Required range: 1 <= x <= 10

Example:

5

kb_min_score

number

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

Required range: 0 <= x <= 1

Example:

0.5

is_published

boolean

Whether this version is published

Example:

false

default_dynamic_variables

object

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).

Example:

{
  "firstName": "John",
  "lastName": "Doe",
  "courseType": "Math"
}

fallback_llm_enabled

boolean

Enable fallback LLM for this agent

Example:

false

llm_fallback_delay_ms

integer | null

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.

Required range: x >= 0

Example:

200

llm_fallback_model

string | null

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.

Example:

"llm_A1B2C3D4E5F6G7"

predictive_preprocessing_enabled

boolean

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

Example:

false

voice_model_id

string

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.

Example:

"vm4k2p9x7q1z3r"

voice_speed

number

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.

Required range: 0.25 <= x <= 4

Example:

1

speech_to_speech_english_accent

enum<string>

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

Available options:

indian,

british,

american

voice_temperature

number

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

Required range: 0 <= x <= 2

Example:

1

voice_volume

number

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.

Required range: -10 <= x <= 10

Example:

0

voice_pitch

number

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

Required range: -20 <= x <= 20

Example:

0

agent_identity

string

Agent identity (required for Conversational_Flow_Agent type on update)

Example:

"You are a helpful customer support agent named Sarah."

agent_background

string

Agent background (required for Conversational_Flow_Agent type on update)

Example:

"You have 5 years of experience in customer support and specialize in helping customers with technical issues."

post_call_analysis

object[]

Fields to extract after a call. Names must be unique and SELECTOR fields need choices. On update, replaces the full list for the draft version.

Show child attributes

agent_functions

object[]

Agent functions for this version. The list replaces the existing functions, except the platform end_call function, which is always kept. Pass an empty array to remove the others.

Show child attributes

post_call_analysis_llm_id

string | null

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:

"llm_A1B2C3D4E5F6G7"

pronunciations

object[]

Pronunciation overrides. Applied by ElevenLabs and Cartesia voices; other providers ignore them. Only items with phonetic_pronunciation are applied.

Show child attributes

Response

Agent updated successfully.

success

enum<boolean>

required

Available options:

true

error

enum<boolean>

required

Available options:

false

statusCode

integer

required

Example:

200

message

string

required

Example:

"Success"

data

object

required

Show child attributes

timestamp

string<date-time>

required

curl --request PATCH \
  --url https://api.dialnexa.com/v1/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version_number": 0,
  "title": "Customer Support Agent",
  "llm_id": "llm_A1B2C3D4E5F6G7",
  "fallback_stt_enabled": true,
  "stt_fallback_transcriber_id": "trs_soniox",
  "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7"
}
'

{
  "success": true,
  "error": false,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "id": "agent_2g7Xy3tY53gRlp",
    "folder_id": null,
    "current_version_number": "0",
    "timezone": "Asia/Kolkata",
    "agent_type": "Single_Prompt_Agent",
    "pipeline_type": "Cascaded",
    "webhook_id": null,
    "current_version": {
      "agent_id": "agent_2g7Xy3tY53gRlp",
      "version_number": "0",
      "version_title": "Version 0",
      "title": "Customer Support Agent",
      "is_published": false,
      "language_id": "lang_en_in",
      "voice_id": "voice_abc123",
      "llm_id": "llm_A1B2C3D4E5F6G7",
      "transcriber_id": "trs_deepgram_nova_2",
      "fallback_stt_enabled": true,
      "stt_fallback_transcriber_id": "trs_soniox"
    },
    "versions": [
      {
        "agent_id": "agent_2g7Xy3tY53gRlp",
        "version_number": "0",
        "version_title": "Version 0",
        "title": "Customer Support Agent",
        "is_published": false,
        "language_id": "lang_en_in",
        "voice_id": "voice_abc123",
        "llm_id": "llm_A1B2C3D4E5F6G7",
        "transcriber_id": "trs_deepgram_nova_2",
        "fallback_stt_enabled": true,
        "stt_fallback_transcriber_id": "trs_soniox"
      }
    ],
    "inbound_phone_numbers": [],
    "outbound_phone_numbers": [
      {
        "id": "phn_abc123",
        "phone_number": "9876543210",
        "country_iso": "91",
        "nickname": "Support line",
        "sip_trunk_enabled": false,
        "linked_at": "2026-09-30T06:00:00.000Z"
      }
    ]
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Overview

Endpoints

When to use this

Minimal publish request

Post-Call Analysis LLM

Publishing And Phone Number Assignment

Fallback STT

Speech And Model Settings

Publish Checks And Voice Tuning

Null Values On Update

Call Settings

Validation Rules

Workspace Model Availability

Check Prompt Health

Create And Update Agent Field Validation

Update Primary And Secondary Languages

Update Agent while batches run

Retired Language Models

Configure Emotion Tags

Configure Contact Memory

Verify the result

Authorizations

Path Parameters

Body

Response

​When to use this

​Minimal publish request

​Post-Call Analysis LLM

​Publishing And Phone Number Assignment

​Fallback STT

​Speech And Model Settings

​Publish Checks And Voice Tuning

​Null Values On Update

​Call Settings

​Validation Rules

​Workspace Model Availability

​Check Prompt Health

​Create And Update Agent Field Validation

​Update Primary And Secondary Languages

​Update Agent while batches run

​Retired Language Models

​Configure Emotion Tags

​Configure Contact Memory

​Verify the result

Authorizations

Path Parameters

Body

Response

When to use this

Minimal publish request

Post-Call Analysis LLM

Publishing And Phone Number Assignment

Fallback STT

Speech And Model Settings

Publish Checks And Voice Tuning

Null Values On Update

Call Settings

Validation Rules

Workspace Model Availability

Check Prompt Health

Create And Update Agent Field Validation

Update Primary And Secondary Languages

Update Agent while batches run

Retired Language Models

Configure Emotion Tags

Configure Contact Memory

Verify the result