Update Agent - DialNexa Documentation

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

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

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

Recommended. This endpoint is part of the public /v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.

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 legacy /agents2 update uses a separate body (UpdateAgents2BodyDto). Review the request schema for /v1/agents/{id} in the panel on this page before migrating.

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 list of boosted keywords

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

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

System prompt text for the agent

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

Prompt text used by the agent

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

Welcome message for the agent

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 templates

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

Voice model ID to use for the agent

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"

Response

Agent updated successfully.

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>

Delete AgentDelete an agent by ID from your workspace.

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

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

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

​When to use this

​Minimal publish request

​Post-Call Analysis LLM

​Publishing And Phone Number Assignment

​Fallback STT

​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

Verify the result