Agents

Create Agent

Creates an agent with its first draft version. Optionally include agent_functions and post_call_analysis in the body to set them at creation time.

Phone numbers are linked to the agent, not to a version. Once the agent has a published version, attach numbers with POST /v1/agents/{agentId}/phone-numbers.

post/v1/agents

Request

Base URL: https://api.dialnexa.com
URL: https://api.dialnexa.com/v1/agents
Auth: HTTP bearer

Request body

voicemail_detectionboolean

Indicates whether voicemail detection is enabled

hangup_on_voicemailboolean

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

voicemail_messagestring

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

end_call_on_silence_secnumber

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.

end_call_on_hold_secnumber nullable

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.

max_call_duration_secnumber

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.

ring_duration_secnumber

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.

background_soundstring

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_volumenumber

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.

ambient_noiseboolean

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

responsivenessnumber

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

interruption_sensitivitynumber

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

response_eagernessnumber

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.

denoising_mode'remove_noise' | 'remove_noise_and_speech'

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

denoise_strengthnumber

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

boosted_keywordsstring

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.

boost_dynamic_variablesboolean

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_intervalnumber

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

reminder_message_contentstring nullable

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

transcriber_idstring nullable

ID of the transcriber catalog entry

fallback_stt_enabledboolean

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_idstring nullable

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

stt_fallback_wait_msnumber nullable

Milliseconds to wait for primary STT after fallback finalizes first

audio_cache_enabledboolean

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

folder_idstring

ID of the folder this agent belongs to

agent_type'Single_Prompt_Agent' | 'Conversational_Flow_Agent' | 'IVR_Agent'

Type of the agent

pipeline_type'Cascaded' | 'Speech_To_Speech'

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

titlestring

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.

version_titlestring nullable

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

descriptionstring

Description of the agent

timezonestring

Timezone for the agent

llm_idstring

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.

language_idstring

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.

secondary_language_idsstring[]

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

language_default_messagestring nullable

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

voice_idstring

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.

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

system_prompt_textstring

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

ivr_menuobject

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_messagestring

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.

knowledge_base_idsstring[]

IDs of the knowledge bases attached to this agent version

kb_max_chunksinteger

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

kb_min_scorenumber

Minimum similarity score threshold for RAG results (0 to 1)

default_dynamic_variablesobject

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

voice_model_idstring

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.

voice_speednumber

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.

speech_to_speech_english_accent'indian' | 'british' | 'american'

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

voice_temperaturenumber

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

voice_volumenumber

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.

voice_pitchnumber

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

llm_temperaturenumber

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

fallback_llm_enabledboolean

Enable fallback LLM for this agent

predictive_preprocessing_enabledboolean

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

llm_fallback_delay_msinteger nullable

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

llm_fallback_modelstring nullable

ID of the LLM to use as fallback.

agent_identitystring

Agent identity (required for Conversational_Flow_Agent type on update)

agent_backgroundstring

Agent background (required for Conversational_Flow_Agent type on update)

post_call_analysis_llm_idstring nullable

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 request

{
  "voicemail_detection": true,
  "hangup_on_voicemail": true,
  "voicemail_message": "Hi, please call us back at your convenience.",
  "end_call_on_silence_sec": 20,
  "end_call_on_hold_sec": 20,
  "max_call_duration_sec": 900,
  "ring_duration_sec": 30,
  "reminder_message_interval": 10,
  "folder_id": "f5k2m8x1q9w3zp",
  "agent_type": "Single_Prompt_Agent",
  "pipeline_type": "Cascaded",
  "title": "Customer Support Agent",
  "description": "This agent handles customer support inquiries",
  "timezone": "Asia/Kolkata",
  "llm_id": "llm_A1B2C3D4E5F6G7",
  "language_id": "lang_en_in",
  "voice_id": "voice_abc123",
  "prompt_text": "Hello, how can I assist you today?",
  "system_prompt_text": "You are a helpful customer support agent named Sarah.",
  "welcome_message": "Welcome to our service!",
  "knowledge_base_ids": [
    "kb_abc123",
    "kb_def456"
  ],
  "kb_max_chunks": 5,
  "kb_min_score": 0.5,
  "default_dynamic_variables": {
    "firstName": "John",
    "lastName": "Doe",
    "courseType": "Math"
  },
  "voice_model_id": "vm4k2p9x7q1z3r",
  "voice_speed": 1,
  "voice_temperature": 1,
  "llm_temperature": 1,
  "llm_fallback_delay_ms": 200,
  "llm_fallback_model": "llm_A1B2C3D4E5F6G7",
  "agent_identity": "You are a helpful customer support agent named Sarah.",
  "agent_background": "You have 5 years of experience in customer support and specialize in helping customers with technical issues.",
  "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7",
  "pronunciations": [
    {
      "original_word": "Nexa",
      "pronunciation_format": "Nek-sa",
      "phonetic_pronunciation": "Nek-sa"
    }
  ]
}

Response

Agent created successfully.

successtrue required

errorfalse required

statusCodeinteger required

messagestring required

timestampstring date-time required

Example response

{
  "statusCode": 201,
  "message": "Success",
  "data": {
    "id": "agent_2g7Xy3tY53gRlp",
    "current_version_number": "3",
    "current_version": {
      "version_number": "1",
      "postcall_analysis": [
        {
          "llm_id": "llm_A1B2C3D4E5F6G7"
        }
      ]
    },
    "versions": [
      {
        "version_number": "1",
        "postcall_analysis": [
          {
            "llm_id": "llm_A1B2C3D4E5F6G7"
          }
        ]
      }
    ],
    "organization_id": "o14XKPP84rt22g",
    "inbound_phone_numbers": [
      {
        "id": "phn_abc123",
        "phone_number": "9876543210",
        "country_iso": "91"
      }
    ],
    "outbound_phone_numbers": [
      {
        "id": "phn_abc123",
        "phone_number": "9876543210",
        "country_iso": "91"
      }
    ],
    "running_batches": [
      {
        "id": "batch_2g7Xy3tY53gRlp"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.