Create Agent

Create a new AI voice agent on the v1 API.

POST /v1/agents

Create Agent

cURL

curl --request POST \
  --url https://api.dialnexa.com/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "title": "Customer Support Agent",
  "language_id": "lang_en_in",
  "voice_id": "voice_abc123",
  "llm_id": "llm_A1B2C3D4E5F6G7",
  "transcriber_id": "trs_deepgram_nova_2",
  "system_prompt_text": "You are a helpful support agent. Confirm the customer issue and summarize next steps.",
  "fallback_stt_enabled": true,
  "stt_fallback_transcriber_id": "trs_soniox",
  "post_call_analysis": [
    {
      "field_name": "issue_type",
      "field_type": "STRING",
      "field_description": "Main customer issue discussed on the call"
    }
  ],
  "predictive_preprocessing_enabled": false,
  "outbound_phone_number_id": "phn_def456",
  "agent_type": "Single_Prompt_Agent",
  "prompt_text": "You are a helpful support agent. Confirm the customer's issue and summarize next steps."
}
EOF

201

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

{
  "title": "Customer Support Agent",
  "language_id": "lang_en_in",
  "voice_id": "voice_abc123",
  "prompt_text": "Greet the caller, understand the issue, and summarize the next step."
}

The request panel contains every advanced field. Treat omitted optional fields as the safest starting point rather than copying the entire schema.

Fallback STT, Boosted Keywords, 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. The fallback transcriber ID must differ from transcriber_id.

Use boosted_keywords when a cascaded agent uses Deepgram or Soniox and important names or product terms are being misheard. Send a comma-separated string. Each term can contain letters, numbers, and spaces only, with up to 100 normalized terms, 50 characters per term, and 2,000 total characters.

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, Predictive Preprocessing, And Prompt Caching

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.

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 create request validates several fields before the draft is created.

Field	Rule
prompt_text and welcome_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 selected voice_id. Omit it when you want DialNexa to apply the recommended model.
stt_fallback_transcriber_id	Required when fallback_stt_enabled is true and must differ from the 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.

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

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

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 spoken when voicemail is detected and hangup_on_voicemail is false. Supports Handlebars template syntax such as {{variable}} and must be valid Handlebars template text.

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

Seconds of silence after which the call is automatically ended. Accepted range: 15 to 30 seconds. Must be more than 5 seconds above reminder_message_interval when reminders are configured.

Required range: 15 <= x <= 30

Example:

20

max_call_duration_sec · number · default: 600

Maximum call duration in seconds before the call is forcibly ended. Accepted range: 60 to 5400 seconds for cascaded agents. Speech to Speech agents are capped at 3600 seconds.

Required range: 60 <= x <= 5400

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 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 · 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. Required when fallback_stt_enabled is true and must differ from 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"

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

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

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

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

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

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

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:

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

Show child attributes

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.

Show child attributes

post_call_analysis · object[]

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

Show child attributes

postcall_analysis · object[]

Alias for post_call_analysis (backward compatibility).

Show child attributes

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

prompt_caching_enabled · boolean

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

Example:

false

Response

201

application/json

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

Show child attributes

versions · object[]

Show child attributes

created_at · string<date-time>

updated_at · string<date-time>