Create Agent

POST

agents

Create Agent

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": "TEXT",
      "field_description": "Main customer issue discussed on the call"
    }
  ],
  "agent_type": "Single_Prompt_Agent",
  "prompt_text": "You are a helpful support agent. Confirm the customer's issue and summarize next steps."
}
EOF

import requests

url = "https://api.dialnexa.com/v1/agents"

payload = {
    "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": "TEXT",
            "field_description": "Main customer issue discussed on the call"
        }
    ],
    "agent_type": "Single_Prompt_Agent",
    "prompt_text": "You are a helpful support agent. Confirm the customer's issue and summarize next steps."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: 'TEXT',
        field_description: 'Main customer issue discussed on the call'
      }
    ],
    agent_type: 'Single_Prompt_Agent',
    prompt_text: 'You are a helpful support agent. Confirm the customer\'s issue and summarize next steps.'
  })
};

fetch('https://api.dialnexa.com/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => 'TEXT',
                'field_description' => 'Main customer issue discussed on the call'
        ]
    ],
    'agent_type' => 'Single_Prompt_Agent',
    'prompt_text' => 'You are a helpful support agent. Confirm the customer\'s issue and summarize next steps.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/agents"

	payload := strings.NewReader("{\n  \"title\": \"Customer Support Agent\",\n  \"language_id\": \"lang_en_in\",\n  \"voice_id\": \"voice_abc123\",\n  \"llm_id\": \"llm_A1B2C3D4E5F6G7\",\n  \"transcriber_id\": \"trs_deepgram_nova_2\",\n  \"system_prompt_text\": \"You are a helpful support agent. Confirm the customer issue and summarize next steps.\",\n  \"fallback_stt_enabled\": true,\n  \"stt_fallback_transcriber_id\": \"trs_soniox\",\n  \"post_call_analysis\": [\n    {\n      \"field_name\": \"issue_type\",\n      \"field_type\": \"TEXT\",\n      \"field_description\": \"Main customer issue discussed on the call\"\n    }\n  ],\n  \"agent_type\": \"Single_Prompt_Agent\",\n  \"prompt_text\": \"You are a helpful support agent. Confirm the customer's issue and summarize next steps.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Customer Support Agent\",\n  \"language_id\": \"lang_en_in\",\n  \"voice_id\": \"voice_abc123\",\n  \"llm_id\": \"llm_A1B2C3D4E5F6G7\",\n  \"transcriber_id\": \"trs_deepgram_nova_2\",\n  \"system_prompt_text\": \"You are a helpful support agent. Confirm the customer issue and summarize next steps.\",\n  \"fallback_stt_enabled\": true,\n  \"stt_fallback_transcriber_id\": \"trs_soniox\",\n  \"post_call_analysis\": [\n    {\n      \"field_name\": \"issue_type\",\n      \"field_type\": \"TEXT\",\n      \"field_description\": \"Main customer issue discussed on the call\"\n    }\n  ],\n  \"agent_type\": \"Single_Prompt_Agent\",\n  \"prompt_text\": \"You are a helpful support agent. Confirm the customer's issue and summarize next steps.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Customer Support Agent\",\n  \"language_id\": \"lang_en_in\",\n  \"voice_id\": \"voice_abc123\",\n  \"llm_id\": \"llm_A1B2C3D4E5F6G7\",\n  \"transcriber_id\": \"trs_deepgram_nova_2\",\n  \"system_prompt_text\": \"You are a helpful support agent. Confirm the customer issue and summarize next steps.\",\n  \"fallback_stt_enabled\": true,\n  \"stt_fallback_transcriber_id\": \"trs_soniox\",\n  \"post_call_analysis\": [\n    {\n      \"field_name\": \"issue_type\",\n      \"field_type\": \"TEXT\",\n      \"field_description\": \"Main customer issue discussed on the call\"\n    }\n  ],\n  \"agent_type\": \"Single_Prompt_Agent\",\n  \"prompt_text\": \"You are a helpful support agent. Confirm the customer's issue and summarize next steps.\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "error": false,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "id": "agent_2g7Xy3tY53gRlp",
    "folder_id": null,
    "current_version_number": "0",
    "timezone": null,
    "agent_type": "Single_Prompt_Agent",
    "pipeline_type": "Cascaded",
    "webhook_id": null,
    "current_version": {
      "agent_id": "agent_2g7Xy3tY53gRlp",
      "version_number": "0",
      "version_title": "Version 0",
      "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"
    },
    "versions": [
      {
        "agent_id": "agent_2g7Xy3tY53gRlp",
        "version_number": "0",
        "version_title": "Version 0",
        "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"
      }
    ],
    "inbound_phone_numbers": [],
    "outbound_phone_numbers": []
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

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. For an IVR Agent, set agent_type to IVR_Agent and provide ivr_menu. IVR is available to every workspace and is marked Beta in the dashboard. See Build IVR Agents before constructing the graph.

Minimal request

Only prompt_text is required. Send title, language_id, and voice_id as well so the agent is created the way you intend: when title is omitted the agent is named “Nexa Agent N”, when voice_id is omitted DialNexa uses its default voice, and when language_id is omitted the language comes from the voice (or the platform default, Hinglish). An omitted or unknown, non-retired llm_id is replaced by the default model rather than rejected, so read the saved values from the response. 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. Fallback transcription is on by default: when you omit stt_fallback_transcriber_id, DialNexa picks a fallback suited to the agent’s languages, or leaves fallback off when none fits. If you send fallback_stt_enabled: true and none fits, the request returns 400. To choose one yourself, pick the ID from List Fallback Transcribers. The fallback transcriber ID must differ from transcriber_id. A requested fallback that cannot serve the agent’s languages is replaced with a compatible one; if none fits, fallback is turned off. Read stt_fallback_transcriber_id and fallback_stt_enabled from the response to see what was saved. Use boosted_keywords when a cascaded agent uses Deepgram, Soniox or Sarvam (for Sarvam the terms are a best-effort hint) 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. Set boost_dynamic_variables to true when values from the test-call form or batch recipient row should also become recognition hints for that call. It defaults to false. DialNexa sanitizes those values, keeps the configured boosted_keywords first, and appends dynamic terms only while the combined limits permit them. Pass post_call_analysis to define post-call fields at creation time and post_call_analysis_llm_id to choose the LLM that extracts them. The LLM is stored on those fields, so it has no effect when no post-call fields are sent. Both can be changed later with Update Agent.

Phone Numbers And Predictive Preprocessing

Create Agent does not take phone numbers. Numbers are linked to the agent, not to a version, and an agent needs a published version before a number can be attached. Publish the draft with Update Agent, then use Attach Agent Phone Number. Predictive preprocessing is on by default: the agent pre-generates likely next replies between turns, which suits cascaded agents with repeated, predictable scripts. Only DialNexa can turn it off, so sending predictive_preprocessing_enabled: false returns 403 Forbidden, except when DialNexa has already switched it off itself because the agent has functions configured or is a Conversational Flow agent. audio_cache_enabled follows the same rule: on by default, and false 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 instructions only. Template variables return `400`; use `prompt_text` for dynamic values. When omitted, the version stores DialNexa’s default voice-agent system prompt, and responses return it in `system_prompt_text`.
`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`	Optional: when omitted, DialNexa picks a fallback for the agent’s languages. When sent with fallback enabled, it must differ from the primary `transcriber_id`; sending the same ID for both returns `400 Bad Request`. A requested fallback that cannot serve the agent’s languages is replaced with a compatible one, and when none fits, fallback is turned off rather than refused. When `fallback_stt_enabled: true` is sent without this ID and no fallback fits the agent’s languages, the request returns `400`.
`default_dynamic_variables.agent_transfer_destinations`	Conversational Flow Agents only. Supports up to `7` pipe-separated transfer numbers. Each must be US `+1` or India `+91` with exactly `10` digits after the country code. Single Prompt Agent requests that include this key return `400 Bad Request`.
`end_call_on_silence_sec`	Must be `15` to `30` seconds. The rule that it is at least `5` seconds above `reminder_message_interval` is checked when either value is later updated, not on create.
`max_call_duration_sec`	Must be `60` to `5,400` seconds for cascaded agents. Speech to Speech agents are capped at `3,600` seconds.
`knowledge_base_ids`	Not accepted for Speech to Speech agents: sending any returns `400` (`Knowledge bases cannot be attached to speech-to-speech agents`).
`version_title`	Maximum 150 characters.
`agent_type: "IVR_Agent"`	The `ivr_menu` graph and static prompt text are checked when the agent is published, not on create, so a draft can be saved with an incomplete menu.
LLM IDs when functions are configured	The primary and enabled fallback models must support tool calling. Check compatibility in the dashboard or MCP catalog; API-key model responses contain only `id`, `name`, and `provider`.

Workspace Model Availability

Choose the primary model from List LLMs and an enabled fallback from List Fallback LLMs using the same workspace key.

Check Prompt Health

Create and update responses include prompt_health for Single Prompt and Speech to Speech agents: status, prompt_tokens, limit_tokens, system_prompt_reserved_tokens, limited_by, and comment. Other types report not_applicable. Counts are estimates, with known dynamic defaults expanded and system instructions reserved. Read prompt size limits before changing models or adding large defaults. The size limit is enforced only when publishing: creating an agent or updating a draft with an oversized prompt succeeds and reports over_ceiling, and publishing that version returns 400. Reduce the prompt or select a suitable model before publishing. Enabled fallback LLM and STT choices must differ from their primary model or transcriber. An invalid pair returns 400. When functions are configured, the primary and fallback LLM must both support tool calling; a model that does not returns 400. The automatically provided End Call behavior does not count as a callable tool for predictive preprocessing or model tool-compatibility checks.

Create And Update Agent Field Validation

Both operations validate each item in agent_functions and post_call_analysis before saving. Invalid items return 400 Bad Request.

agent_functions must be an array. Each item requires a supported type. Optional displayName (or display_name) and description must be strings; config must be an object.
Post-call fields require a non-blank, unique field_name and one of TEXT, SELECTOR, BOOLEAN, NUMBER, or DATETIME. Use TEXT instead of STRING and SELECTOR instead of ENUM.
A SELECTOR requires at least one non-blank string choice in additional_fields, normally an array such as ["Resolved", "Escalated"]. display_order, when supplied, must be a non-negative integer.
llm_fallback_delay_ms and reminder_message_interval cannot be negative. A reminder interval of 0 disables reminders.
ring_duration_sec defaults to 30 seconds and applies to outbound Plivo calls in every workspace. Numeric input is rounded and clamped to 10 through 30: 5 saves as 10, 90 as 30, and 22.6 as 23. Non-numeric input returns 400. Read the saved value to verify it.
end_call_on_hold_sec accepts 10 to 60 seconds. New agents use 20 when omitted or null. On update, null is ignored and the stored value is kept. Read End Call on Hold for behavior and testing.

On update, send the complete intended function or post-call list because each supplied list replaces its previous contents. Read the draft back with Get Agent and verify the saved fields before publishing.

Configure Primary And Secondary Languages

Use language_id for the primary language and secondary_language_ids for up to three additional language IDs. Their order controls language hint priority. On update, send an empty secondary array to clear it. Choose a voice that supports every selected language. Unsupported secondary choices can be dropped on save, so review the saved draft before publishing. For cascaded agents, publishing also requires a primary transcriber compatible with the complete language set. Speech to Speech agents do not use a separate transcriber. Use List Voice Language Options and List Voices to find compatible choices. A Speech-to-Speech agent with secondary languages runs on Gemini Live, so its LLM must be a model whose provider is gemini in List LLMs. When llm_id is omitted, Create Agent picks a Gemini Speech-to-Speech model for it. A model from another provider returns 400. Update Agent applies the same rule. speech_to_speech_english_accent sets the accent of the agent’s English on Speech-to-Speech calls: indian (default), british or american. The optional language_default_message accepts up to 500 characters for a response to an unsupported caller language, spoken with the primary-language voice. On update, null and an empty string are ignored and the stored message is kept. This API field is not an extra visible input in the dashboard language dialog.

Pronunciations

Send pronunciations to control how the voice says specific words. It is an optional list; each item has original_word (the word as written), pronunciation_format (how the voice should say it) and an optional phonetic_pronunciation. Each value is a string of up to 128 characters. Pronunciations are applied by ElevenLabs and Cartesia voices, and only items with phonetic_pronunciation are applied; other voice providers ignore them.

Retired Language Models

GPT-4.1 Nano is retired. Choose current primary, fallback, and post-call extraction models when creating an agent or changing its model selection. A new retired-model selection returns 400 with code LLM_RETIRED; publishing and dialing with a retired primary or enabled fallback are also refused. Read the saved model choices before testing.

Configure Emotion Tags

Set emotion_tags_enabled to true for emotional delivery on Cartesia Sonic 3/3.5 or Soniox TTS v2 voices. It defaults to false on create. Explicitly enabling it for an unsupported voice model returns 400; changing to an unsupported voice turns it off. On update, omission leaves the value unchanged unless that voice change disables it. See Emotion tags for testing guidance.

Configure Contact Memory

Contact memory lets your agents remember earlier calls with the same phone number. Each workspace keeps one memory per contact phone number, and every agent in the workspace shares it. Two fields control it, and both default to false:

Field	What it does
`lead_memory_save_enabled`	After each successful phone call this agent makes or answers, the contact’s memory is updated with what was said, such as decisions, dates, offers and open follow-ups.
`lead_memory_enabled`	When a phone call starts, this agent receives the contact’s memory, so it does not ask for details the contact already gave on an earlier call.

A call is saved when it completes normally and the contact speaks. Voicemail, calls where the contact never speaks, and web calls are not saved, and web calls never use memory. Memory builds from the first call saved after you turn saving on; earlier calls are not added. In the dashboard, both settings are in the agent’s Knowledge Base & Memory section.

Verify the result

Store the returned id, confirm current_version.version_number is "0" (version numbers are returned as strings), then publish the draft with version_number: 0 (a JSON number) and is_published: true before placing a call. Responses can include additional fields not listed here; you can ignore them. 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

prompt_text

string

required

Main instructions for the agent. Supports Handlebars template syntax ({{variable}}) for dynamic content. Must be valid Handlebars: malformed syntax causes errors at call time.

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

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

Example:

true

lead_memory_enabled

boolean

default:false

Show the lead's earlier successful calls in this workspace to the agent at the start of its next call with them

Example:

false

lead_memory_save_enabled

boolean

default:false

Save what was said on this agent's successful calls to lead memory, so agents in this workspace can use it on later calls with the same lead

Example:

false

voicemail_message

string

Message spoken when voicemail is detected (only used when hangup_on_voicemail is false). Supports Handlebars template syntax ({{variable}}). Must be valid Handlebars.

Example:

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

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 at least 5 seconds above reminder_message_interval when reminders are configured.

Required range: 15 <= x <= 30

Example:

20

end_call_on_hold_sec

number | null

Seconds to wait during a sustained detected hold before ending a non-IVR call, 10 to 60. On create, omitted or null uses the default of 20.

Required range: 10 <= x <= 60

Example:

20

max_call_duration_sec

number

default:900

Maximum call duration in seconds before the call is forcibly ended. Maximum accepted: 3600 seconds for speech-to-speech agents, 5400 seconds for cascaded agents.

Required range: 60 <= x <= 5400

Example:

900

ring_duration_sec

number

default:30

Ring timeout for outbound Plivo calls in every workspace, default 30 seconds. Numeric input is rounded to a whole second and clamped to 10 through 30: 5 saves as 10, 90 as 30, and 22.6 as 23. Non-numeric input is rejected. Read the saved value after updating. Has no effect on inbound or web calls.

Example:

30

background_sound

string

Background sound identifier. When ambient_noise is on, calls play the built-in background track whatever value is set; set it to a value other than none for background_sound_volume to apply.

background_sound_volume

number

default:1

Volume of the background sound (0 to 2). Applied only when ambient_noise is true and background_sound is set to a value other than none.

Required range: 0 <= x <= 2

ambient_noise

boolean

default:true

Ambient noise playback on the call. On by default when omitted.

responsiveness

number

default:0

Seconds to wait after the caller stops speaking, 0 to 1. Stored on the agent version; not applied to calls.

Required range: 0 <= x <= 1

interruption_sensitivity

number

default:0.5

Interruption sensitivity level (0 to 1). Stored on the agent version; not applied to calls.

Required range: 0 <= x <= 1

response_eagerness

number

How eagerly the agent responds (0 to 1). Applied when the transcriber is Sarvam or Deepgram (Nova-2, Nova-3, Flux); Soniox agents ignore it. Defaults to 0.9 on create.

Required range: 0 <= x <= 1

listening_backchannel

boolean

default:false

When true, the agent plays short listening sounds ("uh-huh", "right") while the caller is still talking, so a long explanation is not met with silence. Independent of backchanneling (acknowledgements after the caller stops). Defaults to false.

listening_backchannel_frequency

number

default:0.8

How often a listening sound plays when one is possible, 0 (never) to 1 (every opportunity). Only used when listening_backchannel is true. Defaults to 0.8.

Required range: 0 <= x <= 1

denoising_mode

enum<string>

Denoising mode. Only remove_noise turns denoising on; remove_noise_and_speech leaves it off. Web calls run without denoising.

Available options:

remove_noise,

remove_noise_and_speech

denoise_strength

number

Noise suppression strength 0 to 4 (higher is stronger). Defaults to 1 on create.

Required range: 0 <= x <= 4

boosted_keywords

string

Comma-separated list of words or phrases (e.g. "DialNexa, NexaFlow, customer success") used to bias the speech-to-text provider toward recognizing them correctly. This is a recognition bias, not a guarantee: it increases the likelihood of correctly transcribing uncommon names, brands, products, and domain vocabulary. Supported for Deepgram and Soniox transcribers (primary or fallback). Normalized to at most 100 unique terms (case-insensitive, duplicates removed, empty entries dropped) at the configuration boundary; empty/null means no boosted keywords.

Maximum string length: 2000

boost_dynamic_variables

boolean

default:false

When true, each call's dynamic-variable VALUES (from the test-call form or a batch-call CSV lead: names, cities, order IDs) are appended to boosted_keywords for that call, so per-call uncommon words get the same recognition bias. Values are sanitized first (punctuation stripped, over-long entries dropped) and never evict the agent's own configured terms, which always come first. Applies to Deepgram and Soniox only; defaults to false.

reminder_message_interval

number

default:10

Seconds of silence before a reminder. Zero disables reminders. Keep at least five seconds below end_call_on_silence_sec when enabled.

Required range: x >= 0

Example:

10

reminder_message_content

string | null

Reminder text spoken after reminder_message_interval seconds of silence, up to 150 characters. When unset, a language-appropriate default is spoken.

Maximum string length: 150

transcriber_id

string | null

ID of the transcriber catalog entry

fallback_stt_enabled

boolean

default:true

Run a fallback transcriber in parallel with the primary one. On create it defaults to on whenever DialNexa can pick a fallback transcriber for the agent's languages.

stt_fallback_transcriber_id

string | null

Fallback transcriber. When omitted on create, DialNexa picks one suited to the agent's languages; it must differ from transcriber_id.

stt_fallback_wait_ms

number | null

Milliseconds to wait for primary STT after fallback finalizes first

Required range: x >= 0

audio_cache_enabled

boolean

default:true

TTS audio caching for this agent. On by default; only DialNexa can turn it off, so sending false returns 403.

emotion_tags_enabled

boolean

default:false

When true, the agent may write inline emotion tags (e.g. [sad], [excited]) that the voice performs. Supported only on Cartesia Sonic 3 and Soniox TTS v2 voices: turning it on for any other voice returns 400, and switching the voice to an unsupported one turns it off. Defaults to false.

folder_id

string

ID of the folder this agent belongs to

Example:

"f5k2m8x1q9w3zp"

agent_type

enum<string>

default:Single_Prompt_Agent

Type of the agent

Available options:

Single_Prompt_Agent,

Conversational_Flow_Agent,

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

title

string

Title of the agent, 1 to 70 characters. When omitted, DialNexa names it "Nexa Agent N", where N is one more than the number of agents ever created in the workspace, deleted ones included.

Required string length: 1 - 70

Example:

"Customer Support Agent"

version_title

string | null

Version title, 1 to 150 characters. If omitted on create, the first version is titled "Version 0".

Required string length: 1 - 150

Example:

null

description

string

Description of the agent

Example:

"This agent handles customer support inquiries"

timezone

string

Timezone for the agent

Example:

"Asia/Kolkata"

llm_id

string

ID of the primary LLM. When omitted, unknown, or a text model on a Speech to Speech agent, DialNexa uses its default model instead of returning an error; read the saved llm_id from the response.

Example:

"llm_A1B2C3D4E5F6G7"

language_id

string

ID of the primary language. When omitted, DialNexa uses the language of the voice's model, or the platform default (Hinglish) when the voice has no single language.

Example:

"lang_en_in"

secondary_language_ids

string[]

Up to three additional language IDs in priority order. The chosen voice must support them. Send an empty array on update to clear.

Maximum array length: 3

language_default_message

string | null

Optional message for an unsupported caller language, up to 500 characters, spoken in the primary language voice.

Maximum string length: 500

voice_id

string

ID of the voice the agent speaks with. Use GET /v1/voices to browse available voices. When omitted, DialNexa uses its default voice. Speech to Speech agents always get a voice compatible with their model.

Example:

"voice_abc123"

system_prompt_text

string

Static system instructions. Template variables such as {{customer_name}} are rejected with 400; use prompt_text for dynamic content.

Example:

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

IVR menu tree for IVR_Agent type: {entry_node, nodes{...}} with per-node prompt text + digit->node edges. Prompt audio is rendered + cached at publish.

welcome_message

string

Opening message spoken by the agent at the start of the call. Supports Handlebars template syntax ({{variable}}). Must be valid Handlebars: malformed syntax causes errors at call time.

Example:

"Welcome to our service!"

knowledge_base_ids

string[]

IDs of the knowledge bases attached to this agent version

Example:

["kb_abc123", "kb_def456"]

kb_max_chunks

integer

Maximum number of RAG chunks to fetch (1 to 10)

Required range: 1 <= x <= 10

Example:

5

kb_min_score

number

Minimum similarity score threshold for RAG results (0 to 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, the reserved key agent_transfer_destinations accepts a pipe-separated list of phone numbers (maximum 7). Each number must use a supported country code: US (+1) or India (+91), followed by exactly 10 digits (e.g. +11234567890|+919876543210).

Example:

{
  "firstName": "John",
  "lastName": "Doe",
  "courseType": "Math"
}

voice_model_id

string

Speech synthesis model for the selected voice. Each voice is tied to a specific provider, and only that provider's models are valid: submitting a model from a different provider will return 400. In most cases this field can be omitted; the recommended model for the chosen voice is applied automatically. For ElevenLabs voices, the supported model is eleven_flash_v2_5. To find supported models for a specific voice, call GET /v1/voices/{voice_id}/voice-models.

Example:

"vm4k2p9x7q1z3r"

voice_speed

number

Voice speed from 0.25 to 4. Values outside this range return 400. Soniox voices clamp it to 0.7 to 1.3. Speech-to-Speech agents apply it on OpenAI Realtime models only; Gemini Live ignores it.

Required range: 0.25 <= x <= 4

Example:

1

speech_to_speech_english_accent

enum<string>

default:indian

Accent of the agent's English on Speech-to-Speech calls, for the whole call: indian (default), british or american.

Available options:

indian,

british,

american

voice_temperature

number

Voice temperature from 0 to 2. Values outside this range return 400. Applied by ElevenLabs and Smallest voices only.

Required range: 0 <= x <= 2

Example:

1

voice_volume

number

Voice volume from -10 to 10. Values outside this range return 400. Applied by Cartesia voices (a negative value plays as 1, maximum 2), Sarvam voices (below 0.1 plays as 1, maximum 3) and Speech-to-Speech agents; other providers ignore it. New agents default to -0.363.

Required range: -10 <= x <= 10

Example:

0

voice_pitch

number

Voice pitch from -20 to 20. Values outside this range return 400. Applied by Sarvam voices only.

Required range: -20 <= x <= 20

Example:

0

llm_temperature

number

LLM temperature from 0 to 2. Values outside this range return 400. Not applied to Speech-to-Speech agents.

Required range: 0 <= x <= 2

Example:

1

fallback_llm_enabled

boolean

Enable fallback LLM for this agent

Example:

false

predictive_preprocessing_enabled

boolean

Enable predictive preprocessing for this agent version. Not applied to Conversational Flow or Speech-to-Speech agents, or to web calls.

Example:

false

llm_fallback_delay_ms

integer | null

Milliseconds to wait before triggering the fallback LLM, a whole number of 0 or more.

Required range: x >= 0

Example:

200

llm_fallback_model

string | null

ID of the LLM to use as fallback.

Example:

"llm_A1B2C3D4E5F6G7"

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 after a call. Names must be unique and SELECTOR fields need choices. On update, replaces the full list for the draft version.

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

post_call_analysis_llm_id

string | null

LLM used for post-call field extraction. Accepts a prefixed ID (for example llm_A1B2C3D4E5F6G7) or a raw ID; null clears it so the default extraction model (gpt-4o-mini) is used. It is stored on the version's existing post-call fields, so it has no effect when the version has none, and a replaced post_call_analysis list creates new fields without it, so they use the default extraction model. On create it is applied to the fields sent in the same request.

Example:

"llm_A1B2C3D4E5F6G7"

pronunciations

object[]

Pronunciation overrides. Applied by ElevenLabs and Cartesia voices; other providers ignore them. Only items with phonetic_pronunciation are applied.

Show child attributes

Response

Agent created successfully.

success

enum<boolean>

required

Available options:

true

error

enum<boolean>

required

Available options:

false

statusCode

integer

required

Example:

201

message

string

required

Example:

"Success"

data

object

required

Show child attributes

timestamp

string<date-time>

required

Create Agent

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": "TEXT",
      "field_description": "Main customer issue discussed on the call"
    }
  ],
  "agent_type": "Single_Prompt_Agent",
  "prompt_text": "You are a helpful support agent. Confirm the customer's issue and summarize next steps."
}
EOF

import requests

url = "https://api.dialnexa.com/v1/agents"

payload = {
    "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": "TEXT",
            "field_description": "Main customer issue discussed on the call"
        }
    ],
    "agent_type": "Single_Prompt_Agent",
    "prompt_text": "You are a helpful support agent. Confirm the customer's issue and summarize next steps."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: 'TEXT',
        field_description: 'Main customer issue discussed on the call'
      }
    ],
    agent_type: 'Single_Prompt_Agent',
    prompt_text: 'You are a helpful support agent. Confirm the customer\'s issue and summarize next steps.'
  })
};

fetch('https://api.dialnexa.com/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => 'TEXT',
                'field_description' => 'Main customer issue discussed on the call'
        ]
    ],
    'agent_type' => 'Single_Prompt_Agent',
    'prompt_text' => 'You are a helpful support agent. Confirm the customer\'s issue and summarize next steps.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/agents"

	payload := strings.NewReader("{\n  \"title\": \"Customer Support Agent\",\n  \"language_id\": \"lang_en_in\",\n  \"voice_id\": \"voice_abc123\",\n  \"llm_id\": \"llm_A1B2C3D4E5F6G7\",\n  \"transcriber_id\": \"trs_deepgram_nova_2\",\n  \"system_prompt_text\": \"You are a helpful support agent. Confirm the customer issue and summarize next steps.\",\n  \"fallback_stt_enabled\": true,\n  \"stt_fallback_transcriber_id\": \"trs_soniox\",\n  \"post_call_analysis\": [\n    {\n      \"field_name\": \"issue_type\",\n      \"field_type\": \"TEXT\",\n      \"field_description\": \"Main customer issue discussed on the call\"\n    }\n  ],\n  \"agent_type\": \"Single_Prompt_Agent\",\n  \"prompt_text\": \"You are a helpful support agent. Confirm the customer's issue and summarize next steps.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Customer Support Agent\",\n  \"language_id\": \"lang_en_in\",\n  \"voice_id\": \"voice_abc123\",\n  \"llm_id\": \"llm_A1B2C3D4E5F6G7\",\n  \"transcriber_id\": \"trs_deepgram_nova_2\",\n  \"system_prompt_text\": \"You are a helpful support agent. Confirm the customer issue and summarize next steps.\",\n  \"fallback_stt_enabled\": true,\n  \"stt_fallback_transcriber_id\": \"trs_soniox\",\n  \"post_call_analysis\": [\n    {\n      \"field_name\": \"issue_type\",\n      \"field_type\": \"TEXT\",\n      \"field_description\": \"Main customer issue discussed on the call\"\n    }\n  ],\n  \"agent_type\": \"Single_Prompt_Agent\",\n  \"prompt_text\": \"You are a helpful support agent. Confirm the customer's issue and summarize next steps.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Customer Support Agent\",\n  \"language_id\": \"lang_en_in\",\n  \"voice_id\": \"voice_abc123\",\n  \"llm_id\": \"llm_A1B2C3D4E5F6G7\",\n  \"transcriber_id\": \"trs_deepgram_nova_2\",\n  \"system_prompt_text\": \"You are a helpful support agent. Confirm the customer issue and summarize next steps.\",\n  \"fallback_stt_enabled\": true,\n  \"stt_fallback_transcriber_id\": \"trs_soniox\",\n  \"post_call_analysis\": [\n    {\n      \"field_name\": \"issue_type\",\n      \"field_type\": \"TEXT\",\n      \"field_description\": \"Main customer issue discussed on the call\"\n    }\n  ],\n  \"agent_type\": \"Single_Prompt_Agent\",\n  \"prompt_text\": \"You are a helpful support agent. Confirm the customer's issue and summarize next steps.\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "error": false,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "id": "agent_2g7Xy3tY53gRlp",
    "folder_id": null,
    "current_version_number": "0",
    "timezone": null,
    "agent_type": "Single_Prompt_Agent",
    "pipeline_type": "Cascaded",
    "webhook_id": null,
    "current_version": {
      "agent_id": "agent_2g7Xy3tY53gRlp",
      "version_number": "0",
      "version_title": "Version 0",
      "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"
    },
    "versions": [
      {
        "agent_id": "agent_2g7Xy3tY53gRlp",
        "version_number": "0",
        "version_title": "Version 0",
        "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"
      }
    ],
    "inbound_phone_numbers": [],
    "outbound_phone_numbers": []
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Overview

Endpoints

When to use this

Before you begin

Minimal request

Fallback STT, Boosted Keywords, And Post-Call Analysis

Phone Numbers And Predictive Preprocessing

Validation Rules

Workspace Model Availability

Check Prompt Health

Create And Update Agent Field Validation

Configure Primary And Secondary Languages

Pronunciations

Retired Language Models

Configure Emotion Tags

Configure Contact Memory

Verify the result

Authorizations

Body

Response

​When to use this

​Before you begin

​Minimal request

​Fallback STT, Boosted Keywords, And Post-Call Analysis

​Phone Numbers And Predictive Preprocessing

​Validation Rules

​Workspace Model Availability

​Check Prompt Health

​Create And Update Agent Field Validation

​Configure Primary And Secondary Languages

​Pronunciations

​Retired Language Models

​Configure Emotion Tags

​Configure Contact Memory

​Verify the result

Authorizations

Body

Response

When to use this

Before you begin

Minimal request

Fallback STT, Boosted Keywords, And Post-Call Analysis

Phone Numbers And Predictive Preprocessing

Validation Rules

Workspace Model Availability

Check Prompt Health

Create And Update Agent Field Validation

Configure Primary And Secondary Languages

Pronunciations

Retired Language Models

Configure Emotion Tags

Configure Contact Memory

Verify the result