Import Agents - DialNexa Documentation

DialNexa agents can be exported as JSON and imported into any workspace. Importing is the fastest way to replicate an agent configuration across workspaces, onboard a new customer with a pre-built setup, or restore an agent from a backup.

Before You Begin

Use an exported DialNexa agent JSON file from a trusted workspace. Keep the original agent available until the imported configuration has been reviewed and tested.

Where to Find the Import Action

On the Agents tab, click the Import Agent button in the top right area of the page (next to Create agent). A file picker opens. Select the JSON file exported from DialNexa. Alternatively, if you are in a folder view, the import button is available at the folder level and will place the imported agent into that folder.

DialNexa Agents list with folder filter, language filter, search, Import agent button, Create agent button, and agent rows.

What the JSON Contains

A DialNexa agent export is a JSON object that captures the full configuration of a specific agent version. The structure includes:

Section	What it stores
Agent metadata	Name, description, and agent type, such as single prompt, conversational flow, or speech to speech.
Conversation stack	Language, voice provider, voice ID, voice model, LLM provider, model, temperature, transcriber
Prompt	System prompt text, including any `{{variable}}` placeholders
Welcome message	The first thing the agent says when a call connects
Voicemail message	The message left if voicemail is detected
Functions	HTTP function definitions with endpoint, method, headers, and parameter mappings
Speech settings	Response eagerness, audio cache, denoising mode, Hinglish map
Call settings	Voicemail detection, end call on silence, max call duration
Post-call analysis	Extracted field definitions (intent, sentiment, custom fields)
Dynamic variable defaults	Fallback values for variables used in the prompt
IVR menu	Menu graph and handoff configuration for an IVR Agent
Agent webhooks	Per-agent webhook endpoint configurations

Import Agents Without Phone Bindings

Exports remove inbound and outbound phone bindings, including nested phone-provider objects. Import also ignores bindings in older JSON files, including legacy telephony-provider IDs. After import, publish the reviewed draft and assign phone numbers explicitly in the destination workspace. IVR exports and imports preserve the menu graph. Review every Connect To Agent target in the destination workspace and set the required fallback variables. Publishing validates the targets and regenerates cached prompt audio.

What Does Not Transfer on Import

Some configuration is workspace-specific and cannot be transferred via JSON.

What is excluded	Why
Phone number assignments	Removed from exports and ignored on import, including older JSON files. Assign numbers explicitly after publishing.
Published version state	The import creates a draft. You must publish explicitly in the new workspace.
Workflow connections	Workflow routing is configured in the destination workspace separately.
Batch call associations	Batch calls reference the imported agent only after you set them up in the new workspace.
Knowledge base attachments	Document files are not embedded in the export JSON. Re-attach files after import.

Importing an agent always creates a draft version. The imported agent will not receive any live traffic until you publish it and assign it to a phone number, workflow, or batch call in the destination workspace.

How to Import

Obtain the export file

In the source workspace, open the agent, click the row action menu or the agent settings menu, and select Export. DialNexa downloads a .json file to your computer.

Open the destination workspace

Switch to the workspace where you want to import the agent. If you manage multiple workspaces, use the workspace switcher in the sidebar.

Click Import Agent

On the Agents tab, click Import Agent. Select the .json file from your computer.

Confirm the import

DialNexa checks that the file contains the required fields and shows the selected file’s name and size. Click Import to confirm. The button shows an importing state while the draft is being created.

Review and adjust the draft

The imported agent opens as a draft. Review the stack settings, prompt, and functions. Update anything that needs to differ in the new workspace (for example, API endpoints that point to a different environment).

Publish and link

When the agent is ready, publish it, then link it to a phone number or workflow, or choose it for a batch call, in this workspace.

DialNexa Upload an agent modal with a selected JSON export file, Remove button, Cancel button, and Import button.

Supported JSON Format

The import endpoint accepts only JSON files exported by DialNexa. Manually authored JSON or files exported from third-party voice AI platforms are not supported. An export is the agent’s record with the exported version under current_version and its functions in agent_functions, shortened here:

{
  "agent_type": "Single_Prompt_Agent",
  "current_version": {
    "title": "Support Agent",
    "description": "Handles support calls",
    "language_id": "lang_abc123",
    "voice_id": "voice_abc123",
    "llm_id": "llm_abc123",
    "prompt_text": "...",
    "conversation_start_type": "user",
    "allow_interruptions": true,
    "json_output_instructions": null
  },
  "agent_functions": [ ... ]
}

The import needs title, description, language_id, voice_id, llm_id, prompt_text, conversation_start_type, allow_interruptions and json_output_instructions, read from current_version, from the first entry in versions, or from the top level. If any is missing, the file is refused with Invalid JSON file: missing fields - ... and nothing is created. Other settings that are absent take their defaults. Extra unrecognized fields are ignored. DialNexa also strips database-only post-call analysis fields from exports before they are imported again, so exported analysis definitions can be reused without carrying internal row IDs into the destination draft. Imports created from older DialNexa exports are normalized to the current agent validation limits. end_call_on_silence_sec is kept between 15 and 30 seconds, max_call_duration_sec is kept between 60 and 5,400 seconds, and backchannel_frequency is kept between 0 and 1. The backchannel field is accepted on import but does not change call behavior. Function display names, the post-call analysis LLM, and the setting that boosts dynamic variable values are preserved when present. Review any normalized values before publishing the draft.

Common Import Errors

Invalid JSON format

The file could not be parsed. This happens if the file was manually edited and introduced a syntax error. Open the file in a JSON validator and fix the structure before retrying.

Unsupported agent type

The agent type value in the JSON is not recognized. This can occur if the file was exported from a newer version of DialNexa than the destination workspace supports. Contact support if this occurs.

Voice or transcriber not available

A voice ID or transcriber referenced in the JSON is not available in the destination workspace’s region or plan. The import succeeds but that specific setting is reset to the workspace default. Review the stack after import.

An imported call setting changed

The export contains a value outside the limits accepted for new agents. DialNexa moves the value to the nearest supported limit so the draft can be created. Review silence detection and maximum call duration before publishing.

Function endpoint is unreachable

Functions are imported as-is but the destination workspace cannot validate endpoints at import time. The function will appear in the agent settings. Test it with a test call after import.

File too large

Import files have a size limit. If the file exceeds the limit (typically caused by a malformed export), re-export from the source agent and retry.

Verify The Imported Agent

Open the imported draft and review its prompt, provider stack, variables, functions, settings, and missing connections. Publish a test version, run a controlled call, and confirm the result in Call History.

Preserve Imported Agent Settings

Importing or duplicating an existing agent preserves its Audio Cache and predictive preprocessing settings, including settings that were disabled on the original. You do not need to enable them just to copy the agent. Changing those restricted settings on an existing agent still follows workspace permissions. Review the saved draft and test it before publishing; import does not restore exported phone bindings.

Verify Copied Speech And Analysis Settings

Import and duplicate flows preserve Noise Suppression Strength, the reminder message text, and the post-call extraction model when present in the source agent. Older values are normalized to current limits: denoising strength stays within levels 0 through 4, and reminder text is limited to 150 characters. Review these settings and the post-call fields before publishing the copy.

Types Of Agents

Choose the right agent type before building or importing.

Agent Templates

Start from a pre-built template instead of an export.

Agent Versions and Publishing

Publish the imported draft to make it live.

Agent Folders

Organize imported agents into the right folder.

​Before You Begin

​Where to Find the Import Action

​What the JSON Contains

​Import Agents Without Phone Bindings

​What Does Not Transfer on Import

​How to Import

​Supported JSON Format

​Common Import Errors

​Verify The Imported Agent

​Preserve Imported Agent Settings

​Verify Copied Speech And Analysis Settings

​Related Reading

Types Of Agents

Agent Templates

Agent Versions and Publishing

Agent Folders

Before You Begin

Where to Find the Import Action

What the JSON Contains

Import Agents Without Phone Bindings

What Does Not Transfer on Import

How to Import

Supported JSON Format

Common Import Errors

Verify The Imported Agent

Preserve Imported Agent Settings

Verify Copied Speech And Analysis Settings

Related Reading