Create Agent

Create a new AI voice agent with a custom voice, LLM, prompt, and telephony settings.

POST /agents2

Create an agent

cURL

curl --request POST \
  --url https://api.dialnexa.com/v1/agents2 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Customer Support Bot",
  "is_published": true,
  "is_deployement": true,
  "folder_id": "fld_abc123",
  "language": {
    "id": "<string>",
    "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...",
    "welcome_message": "Hello! How can I help you today?"
  },
  "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
    }
  },
  "voice": {
    "id": "<string>",
    "model_id": "<string>",
    "settings": {
      "speed": 1,
      "temperature": 0.8,
      "volume": 1,
      "fallback_voices": [
        {}
      ],
      "pronunciations": [
        "<unknown>"
      ]
    }
  },
  "telephony": {
    "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": 2
  },
  "security": {
    "opt_out_sensitive_data_storage": false,
    "opt_in_secure_urls": false
  },
  "analysis": {
    "postcall_analysis": [
      {
        "field_name": "customer_satisfaction",
        "field_type": "NUMBER",
        "field_description": "CSAT score from 1 to 10"
      }
    ]
  },
  "functions": [
    {
      "display_name": "Book Appointment",
      "type": "book_calendar",
      "description": "Books a slot in the calendar when the user confirms.",
      "config": {}
    }
  ],
  "agent_type": "Single_Prompt_Agent",
  "pipeline_type": "Speech_To_Speech"
}
'

201

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

Agents are the core building block in DialNexa. Each agent defines how an AI-powered call should sound and behave, including what it says, how it responds, and what it can do.

When to use this

Use this endpoint to programmatically create agents as part of your onboarding flow, template system, or multi-tenant setup. For example, if each of your customers needs their own agent pre-configured with their business details, this lets you spin them up automatically.

Key fields

• pipeline_type: Use Cascaded for the standard STT, LLM, and TTS pipeline. Use Speech_To_Speech for realtime speech models such as GPT realtime.
• prompts.prompt_text: The system prompt that shapes the agent’s personality, instructions, and scope. Write it clearly; the LLM follows this closely.
• voice: Pass a voice id from List Voices, or configure it inline.
• speech.transcriber_id: Selects the primary STT provider for cascaded agents. Speech to Speech agents do not use a separate transcriber.
• speech.fallback_stt_enabled: Enables a backup STT provider for cascaded agents. When enabled, also send speech.stt_fallback_transcriber_id.
• speech.audio_cache_enabled: Caches repeated TTS phrases for lower latency on cascaded agents. Speech to Speech agents do not use TTS audio cache.
• telephony.call_limits: Set how long a call can run, how long to wait before ending on silence, and how long to ring before giving up.
• functions: Tools the agent can invoke mid-call, such as calendar booking, CRM lookups, or custom webhooks.
• analysis.postcall_analysis: Fields to extract from the transcript after each call (e.g., CSAT score, intent, outcome).
• metadata via dynamic variables: You can reference {{variable_name}} in your prompt; values are injected at call time from the call’s metadata object.

Pipeline Types

Pipeline type	Use it when	Notes
Cascaded	You want separate transcriber, LLM, and voice controls.	This is the default for single prompt agents and supports fallback STT, voice model pricing, and Audio Cache.
Speech_To_Speech	You want a realtime speech model to listen and speak directly.	The model selector is limited to speech-to-speech models, and voice model, transcriber, and Audio Cache controls are not used.

Request example

{
  "title": "Sales Qualifier",
  "agent_type": "Single_Prompt_Agent",
  "pipeline_type": "Cascaded",
  "conversation_start_type": "agent",
  "allow_interruptions": true,
  "prompts": {
    "prompt_text": "You are a friendly sales rep for Acme Corp. Your goal is to understand the caller's needs, qualify whether they are a good fit for the enterprise plan, and schedule a follow-up call with the account team. Be concise and natural. The caller's name is {{customer_name}}.",
    "welcome_message": "Hi {{customer_name}}, thanks for your interest in Acme Corp! I have a few quick questions to help point you in the right direction."
  },
  "telephony": {
    "call_limits": {
      "end_call_on_silence_sec": 120,
      "max_call_duration_sec": 480,
      "ring_duration_sec": 30
    }
  },
  "speech": {
    "transcriber_id": "tr0deepnova3xx",
    "fallback_stt_enabled": true,
    "stt_fallback_transcriber_id": "tr0soniox001xx",
    "stt_fallback_wait_ms": 500,
    "audio_cache_enabled": true
  },
  "analysis": {
    "postcall_analysis": [
      {
        "field_name": "qualified",
        "field_type": "BOOLEAN",
        "field_description": "Whether the lead meets the enterprise criteria"
      },
      {
        "field_name": "follow_up_scheduled",
        "field_type": "BOOLEAN",
        "field_description": "Whether a follow-up call was booked"
      }
    ]
  }
}

Request

curl "https://api.dialnexa.com/v1/agents2" \
  -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.

Body

application/json

title · string · required

Human-readable name for the agent.

Maximum string length: 100

Example:

"Customer Support Bot"

is_published · boolean

Set true to publish this agent after creation.

Example:

true

is_deployement · boolean

Set true to update an existing published agent deployment.

Example:

true

folder_id · string | null

Optional folder ID to organize this agent.

Example:

"fld_abc123"

language · object

Language configuration.

Show child attributes

conversation_start_type · enum<string>

Who speaks first when the call connects.

Available options: user, agent

Example:

"agent"

allow_interruptions · boolean

Whether the caller can interrupt the agent mid-sentence.

Example:

true

prompts · object

Show child attributes

llm · object

Show child attributes

voice · object

Show child attributes

telephony · object

Show child attributes

speech · object

Show child attributes

reminders · object

Show child attributes

security · object

Show child attributes

analysis · object

Show child attributes

functions · object[]

Show child attributes

agent_type · enum<string>

Agent builder type. Speech to Speech uses Single_Prompt_Agent with pipeline_type set to Speech_To_Speech.

Available options: Single_Prompt_Agent, Conversational_Flow_Agent

Example:

"Single_Prompt_Agent"

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

201

application/json

Agent created successfully.

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"