Skip to main content
POST
Create Agent
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.
Agents are the core building block in DialNexa. Each agent defines how an AI-powered call should sound and behave - what it says, how it responds, and what it can do.

When to use this

Use this endpoint to create agents programmatically as part of an onboarding flow, template system, or multi-tenant setup. The request is scoped to the authenticated organization automatically.

Before you begin

Fetch a language_id from List Languages and a voice_id from List Voices. Creating an agent does not publish its first version.

Minimal request

Start with the four required fields. Add advanced speech, model, fallback, analysis, routing, and function settings only when the basic agent works:
The request panel contains every advanced field. Treat omitted optional fields as the safest starting point rather than copying the entire schema.

Fallback STT And Post-Call Analysis

Use fallback_stt_enabled and stt_fallback_transcriber_id to configure fallback transcription on the first draft version. Pick the fallback transcriber ID from List Fallback Transcribers. If you need post-call fields at creation time, pass post_call_analysis. To change the LLM used for extracting those fields after creation, use Update Agent with post_call_analysis_llm_id.

Phone Numbers And Predictive Preprocessing

You can include inbound_phone_number_id and outbound_phone_number_id when creating the first draft version. The IDs must belong to the authenticated workspace. Creating the agent stores those IDs on the draft, but live dispatch routing is claimed only when the version is published through Update Agent with is_published: true. Use predictive_preprocessing_enabled to turn on predictive preprocessing for the first draft version when your agent should pre-generate likely next replies between turns. This setting is most useful for cascaded agents with repeated, predictable scripts.
The legacy /agents2 endpoint uses a separate, documentation-specific body (CreateAgents2BodyDto). If you are migrating from /agents2, do not assume the bodies are identical - review the request schema for /v1/agents in the panel on this page.

Verify the result

Store the returned id, confirm current_version.version_number is 1, then publish the draft with version_number: 1 and is_published: true before placing a call. If the create request times out, list agents and search for the title before retrying. The contract does not currently publish an idempotency key.

Authorizations

Authorization
string
header
required

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

Body

application/json
title
string
required

Title of the agent (max 70 characters)

Maximum string length: 70
Example:

"Customer Support Agent"

language_id
string
required

ID of the language the agent speaks

Example:

"1"

voice_id
string
required

ID of the voice used by the agent

Example:

"VOICE123456789"

prompt_text
string
required

Prompt text used by the agent

Example:

"Hello, how can I assist you today?"

voicemail_detection
boolean
default:true

Indicates whether voicemail detection is enabled

Example:

true

hangup_on_voicemail
boolean
default:false

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

Example:

false

voicemail_message
string
default:Please leave a message after the beep.

Message played when voicemail is detected (only used when hangup_on_voicemail is false)

Example:

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

listen_for_keypad
boolean
default:true

Whether the agent listens for keypad (DTMF) input from the caller

Example:

true

keypad_timeout_sec
number
default:5

Seconds to wait for keypad input before timing out (0-15)

Required range: 0 <= x <= 15
Example:

5

termination_key
string
default:#

Single character key that ends the call (digits, * or #)

Example:

"#"

digit_limit
number
default:1

Maximum number of DTMF digits to collect from the caller (1-50)

Required range: 1 <= x <= 50
Example:

1

end_call_on_silence_sec
number
default:180

Seconds of silence after which the call is automatically ended (0-1800)

Required range: 0 <= x <= 1800
Example:

180

max_call_duration_sec
number
default:600

Maximum call duration in seconds before the call is forcibly ended

Required range: x >= 0
Example:

600

pause_before_speaking_sec
number
default:2

Seconds of silence inserted before the agent starts speaking

Required range: x >= 0
Example:

0

ring_duration_sec
number
default:5

How long to let the phone ring before treating the call as unanswered (seconds)

Required range: x >= 1
Example:

30

background_sound
string

Background sound file or identifier

background_sound_volume
number
default:1

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
default:0.5

Responsiveness level from 0 to 1.

Required range: 0 <= x <= 1
interruption_sensitivity
number
default:0.5

Interruption sensitivity level (0 to 1)

Required range: 0 <= x <= 1
response_eagerness
number
default:1

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

Required range: 0 <= x <= 1
backchanneling
boolean
default:false

Enable or disable backchanneling

backchannel_frequency
number
default:0.5

Backchannel frequency from (0 to 1)

Required range: 0 <= x <= 1
transcription_mode
enum<string>
default:optimize_for_speed

Mode for transcription

Available options:
optimize_for_speed,
optimize_for_accuracy
denoising_mode
enum<string>

Mode for denoising audio input

Available options:
remove_noise,
remove_noise_and_speech
speech_normalization
boolean
default:false

Enable or disable speech normalization

transcript_formatting
boolean
default:false

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
default:9

Interval between reminder messages (in seconds)

reminder_message_frequency
number
default:1

Frequency of reminder messages

transcriber_id
string | null

ID of the transcriber catalog entry

fallback_stt_enabled
boolean
default:false

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"

agent_type
enum<string>
default:Single_Prompt_Agent

Type of the agent

Available options:
Single_Prompt_Agent,
Conversational_Flow_Agent
Example:

"Single_Prompt_Agent"

pipeline_type
enum<string>
default:Cascaded

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

Available options:
Cascaded,
Speech_To_Speech
Example:

"Cascaded"

version_title
string | null

Version title (optional, will be auto-generated if not provided, max 35 characters)

Maximum string length: 35
Example:

null

description
string

Description of the agent

Example:

"This agent handles customer support inquiries"

timezone
string

Timezone for the agent

Example:

"Asia/Kolkata"

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. Stored on the draft at creation; live outbound routing is claimed when the version is published.

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. Stored on the draft at creation; live inbound routing is claimed when the version is published.

llm_id
string

ID of the LLM associated with the agent

Example:

"A1B2C3D4E5F6G7"

webhook_id
string

ID of the webhook associated with the agent

Example:

"wh_12345678901234"

system_prompt_text
string

System prompt text for the agent

Example:

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

node_positions
string

Node positions for Conversational_Flow_Agent type (stored as JSON string)

Example:

"{\"node1\": {\"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

json_output_instructions
object

Instructions for JSON output

Example:
knowledge_base_ids
string[]

IDs of the knowledge bases attached to this agent version

Example:
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

default_dynamic_variables
object

Default values for dynamic variables used in templates

Example:
voice_model_id
string

Voice model ID to use for the agent

Example:

"voice_model_abc123"

voice_speed
number

Voice speed (0.25 to 4.0)

Required range: 0.25 <= x <= 4
Example:

1

voice_temperature
number

Voice temperature (0.0 to 2.0)

Required range: 0 <= x <= 2
Example:

1

voice_volume
number

Voice volume (0 to 10)

Required range: 0 <= x <= 10
Example:

1

voice_pitch
number

Pitch adjustment of the voice (-1 to 1)

Required range: -1 <= x <= 1
Example:

0

llm_temperature
number

LLM temperature (0.0 to 2.0)

Required range: 0 <= x <= 2
Example:

0.1

opt_out_sensitive_data_storage
boolean

Opt out of sensitive data storage

Example:

false

opt_in_secure_urls
boolean

Opt in to secure URLs

Example:

false

fallback_llm_enabled
boolean

Enable fallback LLM for this agent

Example:

false

predictive_preprocessing_enabled
boolean

Enable predictive preprocessing for this agent version

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"

fallback_voices
object[]

Fallback voices for TTS. Used when the primary voice is unavailable.

agent_functions
object[]

Functions the agent can invoke during a call (e.g. end call, transfer, booking). Passed at create time; use PATCH to replace later.

post_call_analysis
object[]

Fields to extract from the call transcript after the call ends.

postcall_analysis
object[]

Alias for post_call_analysis (backward compatibility).

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

Response

Agent created 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
versions
object[]
created_at
string<date-time>
updated_at
string<date-time>