Update Agent

Update one or more fields on an existing agent. Only fields you include are changed.

PATCH /agents2/{id}

Update an agent

cURL

curl --request PATCH \
  --url https://api.dialnexa.com/v1/agents2/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "is_published": true,
  "is_deployement": true,
  "prompts": {},
  "voice": {},
  "llm": {
    "id": "<string>",
    "fallback": {
      "fallback_llm_enabled": true,
      "llm_fallback_delay_ms": 500,
      "llm_fallback_model": "llm_movqcwtlo7eo53",
      "fall_back_llm_id": "llm_movqcwtlo7eo53"
    },
    "settings": {
      "temperature": 0.1,
      "structured_output": true
    }
  },
  "telephony": {},
  "speech": {
    "background_sound": null,
    "responsiveness": 0.5,
    "interruption_sensitivity": 0.5,
    "backchanneling": false,
    "backchannel_frequency": 0.5,
    "transcription_mode": "optimize_for_speed",
    "denoising_mode": "remove_noise",
    "speech_normalization": false,
    "transcript_formatting": false,
    "transcriber_id": "tr0deepnova3xx",
    "fallback_stt_enabled": false,
    "stt_fallback_transcriber_id": "tr0soniox001xx",
    "stt_fallback_wait_ms": 500,
    "audio_cache_enabled": true
  },
  "analysis": {},
  "functions": [
    {}
  ],
  "pipeline_type": "Speech_To_Speech"
}
'

200

{
  "id": "agt_abc123",
  "organization_id": "org_xyz",
  "folder_id": null,
  "current_version_number": 1,
  "is_deleted": false,
  "createdAt": "2024-03-01T10:00:00.000Z",
  "updatedAt": "2024-03-01T10:00:00.000Z",
  "timezone": null,
  "current_version": {
    "agent_id": "agt_abc123",
    "number": 1,
    "title": "Customer Support Bot",
    "is_published": true,
    "language": {
      "id": "lang_en_us",
      "details": {
        "name": "English",
        "code": "en-US"
      }
    },
    "conversation_start_type": "agent",
    "allow_interruptions": true,
    "prompts": {
      "prompt_text": "You are a helpful customer support agent for Acme Corp. Assist customers with billing inquiries, order status, and returns.",
      "welcome_message": "Hello! How can I help you today?",
      "node_positions": null,
      "json_output_instructions": null,
      "default_dynamic_variables": null
    },
    "voice": {
      "id": "voice_xyz",
      "model_id": "vmod_abc",
      "settings": {
        "speed": 1,
        "temperature": 0.8,
        "volume": 1,
        "pitch": null,
        "fallback_voices": [],
        "pronunciations": []
      }
    },
    "llm": {
      "id": "llm_gpt4o",
      "settings": {
        "temperature": 0.1,
        "structured_output": true
      },
      "fallback": {
        "fallback_llm_enabled": null,
        "llm_fallback_delay_ms": null,
        "llm_fallback_model": null
      }
    },
    "telephony": {
      "inbound": {
        "id": "phn_abc",
        "details": null
      },
      "outbound": {
        "id": null,
        "details": null
      },
      "call_limits": {
        "end_call_on_silence_sec": 180,
        "max_call_duration_sec": 600,
        "pause_before_speaking_sec": 1.5,
        "ring_duration_sec": 30
      }
    },
    "speech": {
      "background_sound": null,
      "responsiveness": 0.5,
      "interruption_sensitivity": 0.5,
      "backchanneling": false,
      "backchannel_frequency": 0.5,
      "transcription_mode": "optimize_for_speed",
      "denoising_mode": "remove_noise",
      "speech_normalization": false,
      "transcript_formatting": false,
      "transcriber_id": "tr0deepnova3xx",
      "fallback_stt_enabled": false,
      "stt_fallback_transcriber_id": "tr0soniox001xx",
      "stt_fallback_wait_ms": 500,
      "audio_cache_enabled": true
    },
    "reminders": {
      "reminder_message_interval": 10,
      "reminder_message_frequency": 1
    },
    "security": {
      "opt_out_sensitive_data_storage": false,
      "opt_in_secure_urls": false
    },
    "analysis": {
      "postcall_analysis": []
    },
    "functions": [],
    "transcriber_id": "tr0deepnova3xx",
    "fallback_stt_enabled": false,
    "stt_fallback_transcriber_id": "tr0soniox001xx",
    "stt_fallback_wait_ms": 500,
    "audio_cache_enabled": true
  },
  "pipeline_type": "Cascaded"
}

Update an existing agent; provide version_number when updating a specific version.

Endpoint

PATCH /agents2/{id}

This page uses Mintlify OpenAPI rendering, including the API tester/runner, request schema, and response schema from the spec.

Updating Pipeline And Speech Settings

Single prompt agents can use either the standard Cascaded pipeline or the Speech_To_Speech pipeline. Changing pipeline_type changes which controls apply to the agent version:

Field	Applies to	Behavior
pipeline_type	Single prompt agents	Cascaded keeps separate transcriber, LLM, and voice controls. Speech_To_Speech uses a realtime speech model.
speech.transcriber_id	Cascaded agents	Selects the primary STT provider.
speech.fallback_stt_enabled	Cascaded agents	Enables backup STT. Set speech.stt_fallback_transcriber_id when this is true.
speech.audio_cache_enabled	Cascaded agents	Enables cached TTS for repeated phrases. Speech to Speech agents ignore this setting.

Request Example

{
  "version_number": 1,
  "title": "Updated Title",
  "conversation_start_type": "user",
  "allow_interruptions": false,
  "prompts": {
    "prompt_text": "Updated greeting message",
    "welcome_message": "Welcome back!"
  },
  "voice": {
    "model_id": null,
    "settings": {
      "speed": 1.2,
      "temperature": 0.9,
      "volume": 1.0
    }
  },
  "llm": {
    "id": null,
    "settings": {
      "temperature": 0.2
    }
  },
  "pipeline_type": "Cascaded",
  "telephony": {
    "voicemail": {
      "voicemail_detection": false,
      "hangup_on_voicemail": true,
      "voicemail_message": "We'll call you back."
    }
  },
  "speech": {
    "backchanneling": true,
    "transcriber_id": "tr0deepnova3xx",
    "fallback_stt_enabled": true,
    "stt_fallback_transcriber_id": "tr0soniox001xx",
    "stt_fallback_wait_ms": 500,
    "audio_cache_enabled": true
  },
  "reminders": {
    "reminder_message_interval": 20
  },
  "security": {
    "opt_in_secure_urls": true
  },
  "analysis": {
    "postcall_analysis": []
  },
  "functions": [
    {
      "display_name": "Book Calendar",
      "type": "book_calendar",
      "description": "Book appointments",
      "config": {
        "api_key": "YOUR_API_KEY"
      }
    }
  ],
  "is_published": true,
  "inbound_phone_number_id": "1234567890abcdef",
  "outbound_phone_number_id": "1234567890abcdef"
}

Request

curl -X PATCH "https://api.dialnexa.com/v1/agents2/agt_k7m2nq9xw4p8" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

Response

{
  "id": "agt_k7m2nq9xw4p8",
  "title": "Sales Qualifier",
  "conversation_start_type": "agent",
  "allow_interruptions": true,
  "is_published": true,
  "prompts": {
    "prompt_text": "You are a friendly sales rep for Acme Corp. Qualify the caller for the enterprise plan. The caller name is {{customer_name}}.",
    "welcome_message": "Hi {{customer_name}}, thanks for calling Acme Corp!"
  },
  "voice": { "id": "vce_en_us_ava", "model_id": "eleven_multilingual_v2" },
  "llm":   { "id": "llm_gpt4o",     "settings": { "temperature": 0.7 } },
  "telephony": {
    "call_limits": { "max_call_duration_sec": 480, "end_call_on_silence_sec": 120, "ring_duration_sec": 30 }
  },
  "analysis": {
    "postcall_analysis": [
      { "field_name": "qualified",         "field_type": "BOOLEAN" },
      { "field_name": "follow_up_booked",  "field_type": "BOOLEAN" }
    ]
  },
  "created_at": "2024-03-01T10:00:00.000Z",
  "updated_at": "2024-05-01T09:30:00.000Z"
}

Authorizations

Authorization · string · header · required

Pass your API key as a Bearer token in the Authorization header.

Path Parameters

id · string · required

Body

application/json

Any subset of agent fields. Unspecified fields are left unchanged.

title · string

is_published · boolean

Set true to publish this agent.

Example:

true

is_deployement · boolean

Set true to update an existing published agent deployment.

Example:

true

prompts · object

voice · object

llm · object

Show child attributes

telephony · object

speech · object

Show child attributes

analysis · object

functions · object[]

pipeline_type · enum<string>

Pipeline subtype for single prompt agents. Defaults to Cascaded when omitted.

Available options: Cascaded, Speech_To_Speech

Example:

"Speech_To_Speech"

Response

200

application/json

Success.

id · string

Example:

"agt_abc123"

organization_id · string

Example:

"org_xyz"

folder_id · string | null

Example:

null

current_version_number · integer

Example:

1

is_deleted · boolean

Example:

false

createdAt · string<date-time>

Example:

"2024-03-01T10:00:00.000Z"

updatedAt · string<date-time>

Example:

"2024-03-01T10:00:00.000Z"

timezone · string | null

Example:

null

current_version · object

Show child attributes

pipeline_type · enum<string> | null

Pipeline subtype for single prompt agents. Cascaded uses separate STT, LLM, and TTS components. Speech_To_Speech uses a realtime speech model.

Available options: Cascaded, Speech_To_Speech

Example:

"Cascaded"