Update Agent

Update an existing agent on the v1 API.

PATCH /v1/agents/{id}

cURL

request

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"
}
'

200

{
  "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"
    }
  ]
}

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

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.

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 system instructions. Use prompt_text for dynamic variables.
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	Supports up to 7 pipe-separated transfer numbers. Each must be US +1 or India +91 with exactly 10 digits after the country code.
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.
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.

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

id · 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"

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 (optional, will be auto-generated if not provided, max 35 characters)

Maximum string length: 35

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 for the agent. Use prompt_text for dynamic content via {{variable}} syntax.

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 · default: 0.1

temperature value for the LLM which controls how creative the model responses are

Example:

0.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:

500

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

Response

200

application/json

Agent updated successfully.

id · string · required

Signed agent ID

Example:

"agent_2g7Xy3tY53gRlp"

agent_type · enum<string> · required

Available options: Single_Prompt_Agent, Conversational_Flow_Agent

folder_id · string | null

current_version_number · integer | null

timezone · string | null

pipeline_type · enum<string> | null

Available options: Cascaded, Speech_To_Speech

webhook_id · string | null

current_version · object | null

Show child attributes

versions · object[]

Show child attributes

created_at · string<date-time>

updated_at · string<date-time>