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": 1,
  "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": 1,
    "timezone": "Asia/Kolkata",
    "agent_type": "Single_Prompt_Agent",
    "pipeline_type": "Cascaded",
    "webhook_id": null,
    "current_version": {
      "agent_id": "agent_2g7Xy3tY53gRlp",
      "version_number": 1,
      "version_title": "Version 1",
      "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",
      "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7"
    },
    "versions": [
      {
        "agent_id": "agent_2g7Xy3tY53gRlp",
        "version_number": 1,
        "version_title": "Version 1",
        "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",
        "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7"
      }
    ]
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

{
  "statusCode": 400,
  "message": "Request validation failed",
  "error": "Bad Request"
}

{
  "statusCode": 401,
  "message": "API key is missing or invalid",
  "error": "Unauthorized"
}

{
  "statusCode": 403,
  "message": "You do not have permission to access this resource",
  "error": "Forbidden"
}

{
  "statusCode": 404,
  "message": "Agent not found",
  "error": "Not Found"
}

{
  "statusCode": 409,
  "message": "Cannot bind outbound_phone_number_id \"phn_def456\" to this agent because it is currently used by active workflows. Pause those workflows first, then retry.",
  "error": "Conflict"
}

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

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, phone number, 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 does not exist in this workspace. See API errors for the standard error format.

Minimal publish request

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

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 setting unchanged.

Send version_number with the request. Published versions cannot be edited, except when publishing a draft.

Publishing And Phone Number Assignment

Phone number assignment becomes live only when you publish a draft. If you send inbound_phone_number_id or outbound_phone_number_id, include is_published: true in the same request so DialNexa can claim the number for that published version. Sending a phone number ID without is_published: true is ignored for live routing. Use an empty string to detach an inbound or outbound phone number while publishing. For outbound numbers, DialNexa can return 409 Conflict if changing or removing the number would break active workflows that still use that number in Voice Call nodes. Pause those workflows first, then retry.

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.

Speech And Model Settings

Use boosted_keywords when a cascaded Deepgram or Soniox agent 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. Use predictive_preprocessing_enabled to pre-generate likely next replies between turns. Use prompt_caching_enabled only when DialNexa has enabled Prompt Caching for your workspace. If the feature is not enabled, the API returns 403 Forbidden. When functions are configured, the primary and fallback LLM must support tool calling. 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 conversation_start_type is agent_defined, valid content in Conversational Flow nodes, and a transcriber compatible with the selected language. 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. Provider-specific controls can have narrower useful ranges. Values outside the API bounds return 400.

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 more than `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.
`version_title`	Maximum 150 characters.
`ivr_menu`	IVR Agents only. Requires a valid entry node, valid edges, static prompt text, and a published non-IVR target for each agent handoff.
LLM IDs when functions are configured	The primary and fallback models must report `supports_tool_calling: true` from the LLM catalog.
Publishing	Can return `409 Conflict` if this agent is tied to a draft, waiting, scheduled, active, or running batch campaign. Resolve the campaign before publishing.

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. An enforced over-limit prompt returns 400 on creation, publishing, or updates that change the prompt, defaults, system instructions, model, fallback selection, or pipeline. Unrelated updates to an existing oversized agent can succeed while reporting over_ceiling. 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.

Verify the result

Fetch the agent and confirm the intended version is published. If the update timed out, read the agent before repeating the request, especially when publishing or assigning a phone number.

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

number

required

Version number of the agent to update

Example:

1

background_sound

string

Background sound file or identifier

background_sound_volume

number

Volume of background sound (0 to 2)

Required range: 0 <= x <= 2

ambient_noise

boolean

Enable or disable ambient noise playback on the call

responsiveness

number

Responsiveness level from 0 to 1.

Required range: 0 <= x <= 5

interruption_sensitivity

number

Interruption sensitivity level (0 to 1)

Required range: 0 <= x <= 1

response_eagerness

number

How eagerly the agent responds (0 to 1). Only applied when transcriber is Soniox.

Required range: 0 <= x <= 1

backchanneling

boolean

Enable or disable backchanneling

backchannel_frequency

number

Frequency of backchannel responses

Required range: 0 <= x <= 1

Example:

0.5

transcription_mode

enum<string>

Mode for transcription

Available options:

optimize_for_speed,

optimize_for_accuracy

denoising_mode

enum<string> | null

Mode for denoising audio input

Available options:

remove_noise,

remove_noise_and_speech

speech_normalization

boolean

Enable or disable speech normalization

transcript_formatting

boolean

Enable or disable transcript formatting

backchannel_keywords

string

Comma-separated list of backchannel keywords

boosted_keywords

string

Comma-separated recognition hints for supported Deepgram and Soniox transcribers. Terms can contain letters, numbers, and spaces only. The normalized list supports up to 100 terms, 50 characters per term, and 2000 total characters.

Maximum string length: 2000

Example:

"DialNexa, Nexa Prime, customer success"

boost_dynamic_variables

boolean

When true, sanitized values from test-call or batch-recipient dynamic variables are appended to boosted_keywords for that call. Configured terms keep priority. Applies to supported Deepgram and Soniox primary and fallback transcribers.

reminder_message_interval

number

Interval between reminder messages (in seconds)

reminder_message_frequency

number

Frequency of reminder messages

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. Required when fallback_stt_enabled is true and must differ from the effective primary transcriber_id.

stt_fallback_wait_ms

number

Milliseconds to wait for primary STT after fallback finalizes first

Required range: x >= 0

audio_cache_enabled

boolean

Enable TTS audio caching for this agent

folder_id

string

ID of the folder this agent belongs to

Example:

"fld_abc123xyz789"

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)

Maximum string length: 70

Example:

"Customer Support Agent"

version_title

string | null

Version title. If omitted, DialNexa generates one automatically. Maximum 150 characters.

Maximum string length: 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"

inbound_phone_number_id

string

ID of the inbound phone number to use for this agent. Must be an existing phone number ID in your organization. Applied to live inbound routing only when is_published: true is sent in the same request. Pass an empty string to detach while publishing.

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

outbound_phone_number_id

string

ID of the outbound phone number to use for this agent. Must be an existing phone number ID in your organization. Applied to live outbound routing only when is_published: true is sent in the same request. Pass an empty string to detach while publishing. Active workflows using the number can cause a 409 conflict.

language_id

string

ID of the language the agent speaks

Example:

"lng_59a9ce4a91334686933a"

llm_id

string

ID of the LLM associated with the agent

Example:

"A1B2C3D4E5F6G7"

llm_temperature

number

Llm temperature from 0 to 2. Values outside this range return 400.

Required range: 0 <= x <= 2

Example:

1

voice_id

string

ID of the voice used by the agent

Example:

"VOICE123456789"

webhook_id

string

ID of the webhook associated with the agent

Example:

"wh_12345678901234"

prompt_text

string

Main instructions for the agent. Supports Handlebars template syntax such as {{variable}} for dynamic content. Must be valid Handlebars template text.

Example:

"Hello, how can I assist you today?"

node_positions

string

Node positions for Conversational_Flow_Agent type (stored as JSON string)

Example:

"{\"id\" : 1, \"positions\" : {\"x\": 100, \"y\": 200}}"

conversation_start_type

enum<string>

Who starts the conversation

Available options:

user,

agent_dynamic,

agent_defined

Example:

"user"

welcome_message

string

Opening message spoken by the agent at the start of the call. Supports Handlebars template syntax such as {{variable}} and must be valid Handlebars template text.

Example:

"Welcome to our service!"

allow_interruptions

boolean

Whether the agent allows interruptions

Example:

true

structured_output

boolean

Whether the reponse should adhere to a structure or not

Example:

true

json_output_instructions

object

Instructions for JSON output

Example:

{ "format": "detailed" }

knowledge_base_ids

string[]

IDs of the knowledge bases attached to this agent version

Example:

["kb_abc123", "kb_def456"]

kb_max_chunks

number

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

Required range: 1 <= x <= 10

Example:

5

kb_min_score

number

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

Required range: 0 <= x <= 1

Example:

0.5

is_published

boolean

Publish this draft version. When true, phone number IDs in the same request are claimed for live routing.

Example:

false

update_deployment

boolean

Whether to allow updating a published version

Example:

false

default_dynamic_variables

object

Default values for dynamic variables used in Handlebars templates. For call-transfer flows, agent_transfer_destinations accepts up to 7 pipe-separated phone numbers. Each number must use US +1 or India +91 and exactly 10 digits after the country code.

Example:

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

fallback_llm_enabled

boolean

Enable fallback LLM for this agent

Example:

false

llm_fallback_delay_ms

number | null

Milliseconds to wait before triggering the fallback LLM

Example:

200

llm_fallback_model

string | null

ID (llms.id) of the LLM to use as fallback

Example:

"abc123xyz789ab"

predictive_preprocessing_enabled

boolean

Enable predictive preprocessing for this agent version

Example:

false

voice_model_id

string

Speech synthesis model for the selected voice. The model must belong to the same provider as voice_id. Omit this field when you want DialNexa to apply the recommended model. For ElevenLabs voices, use eleven_flash_v2_5 where supported. To find supported models for one voice, call GET /v1/voices/{voice_id}/voice-models.

Example:

"254"

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[]

Post call analysis configuration

Show child attributes

Example:

[
  {
    "field_name": "customer_satisfaction",
    "field_type": "NUMBER",
    "field_description": "Customer satisfaction rating"
  }
]

postcall_analysis

object[]

Post call analysis configuration (alternative field name)

Show child attributes

Example:

[
  {
    "field_name": "customer_satisfaction",
    "field_type": "NUMBER",
    "field_description": "Customer satisfaction rating"
  }
]

agent_functions

object[]

Agent functions - full replace for this version. Pass empty array to clear all.

Show child attributes

post_call_analysis_llm_id

string | null

LLM ID used for post-call analysis extraction. Pass a signed LLM ID such as llm_A1B2C3D4E5F6G7 to set an override, null to clear it, or omit the field to leave the existing setting unchanged.

Example:

"llm_A1B2C3D4E5F6G7"

prompt_caching_enabled

boolean

Enable OpenAI Prompt Caching for this agent version. DialNexa must enable this feature for your workspace.

Example:

false

IVR menu graph for IVR_Agent. Prompt audio is rendered and cached when the agent is published.

voice_speed

number

Voice speed from 0.25 to 4. Values outside this range return 400.

Required range: 0.25 <= x <= 4

Example:

1

voice_temperature

number

Voice temperature from 0 to 2. Values outside this range return 400.

Required range: 0 <= x <= 2

Example:

1

voice_volume

number

Voice volume from -10 to 10. Values outside this range return 400.

Required range: -10 <= x <= 10

Example:

0

voice_pitch

number

Voice pitch from -20 to 20. Values outside this range return 400.

Required range: -20 <= x <= 20

Example:

0

reminder_message_content

string | null

Reminder text spoken after reminder_message_interval seconds of silence. Null/empty falls back to the language-detected default.

Maximum string length: 150

denoise_strength

number | null

Noise suppression strength 0-4 (higher = stronger)

Required range: 0 <= x <= 4

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": 1,
  "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": 1,
    "timezone": "Asia/Kolkata",
    "agent_type": "Single_Prompt_Agent",
    "pipeline_type": "Cascaded",
    "webhook_id": null,
    "current_version": {
      "agent_id": "agent_2g7Xy3tY53gRlp",
      "version_number": 1,
      "version_title": "Version 1",
      "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",
      "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7"
    },
    "versions": [
      {
        "agent_id": "agent_2g7Xy3tY53gRlp",
        "version_number": 1,
        "version_title": "Version 1",
        "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",
        "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7"
      }
    ]
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

{
  "statusCode": 400,
  "message": "Request validation failed",
  "error": "Bad Request"
}

{
  "statusCode": 401,
  "message": "API key is missing or invalid",
  "error": "Unauthorized"
}

{
  "statusCode": 403,
  "message": "You do not have permission to access this resource",
  "error": "Forbidden"
}

{
  "statusCode": 404,
  "message": "Agent not found",
  "error": "Not Found"
}

{
  "statusCode": 409,
  "message": "Cannot bind outbound_phone_number_id \"phn_def456\" to this agent because it is currently used by active workflows. Pause those workflows first, then retry.",
  "error": "Conflict"
}

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

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

Validation Rules

Check Prompt Health

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

​Validation Rules

​Check Prompt Health

​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

Validation Rules

Check Prompt Health

Verify the result