> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# DialNexa Batch Call Recipient Files

> Prepare DialNexa batch call CSV files with valid phone numbers, dynamic variable columns, field mapping, and upload checks.

DialNexa batch call recipient files provide the phone numbers and dynamic variable values for outbound campaigns. The create page can download a CSV template based on the selected agent version default variables, then guide operators through mapping, optional name cleanup, phone-number review, and the recipient table.

> [!TIP]
>
> CSV files are simple right up until one header has an invisible extra space. Then they become a personality test.

## Before You Begin

List the variables used by the published agent and collect one valid recipient row for each important scenario. Use consented test numbers before preparing a production file.

## Prepare DialNexa Batch Call Recipient Files

Keep recipient files boring and predictable.

| Column | Purpose |
| - | - |
| phone number | Recipient number in a format the selected outbound route can validate. Use full international format when possible. |
| Dynamic variable columns | Values for placeholders used by the selected published agent version. |
| `notes` | Reserved. Per-recipient data stored on the call and returned on every webhook event, never read by the agent. See [Notes column](#notes-column). |
| Additional columns | Can be shown in the recipient table when parsed, but should not replace required variables. |
| One recipient per row | Each row represents one outbound call target. |

### Notes column

A column named `notes` is reserved. Its value is stored on the call rather than passed to the agent as a dynamic variable, and it comes back in `payload.call.notes` on every [webhook](https://dialnexa.com/docs/api-reference/webhooks/index.md#custom-notes) event for that call. Use it to carry your own record IDs through a batch.

| Cell content | Stored as |
| - | - |
| A JSON object, up to 15 top-level keys | That object, unchanged |
| Plain text | `{"text": "<your text>"}` |
| Empty | Nothing; the call reports `notes: null` |
| Malformed JSON starting with `{` or `[` | Upload fails with `400` |
| A JSON object with more than 15 keys | Upload fails with `400` |

The malformed-JSON case fails deliberately rather than falling back to text, so a broken object is never silently stored as a string.

> [!NOTE]
>
> Retries do not inherit notes. If a recipient is retried, the retry's webhook events report `notes: null` even though the first attempt carried them.

The upload flow reads headers from CSV files and supported spreadsheet files. For Excel uploads, DialNexa converts the mapped sheet data to CSV before sending it for campaign parsing.

Values that contain commas, line breaks, or double quotes must use standard CSV quoting. Wrap the whole value in double quotes and write a literal double quote as two double quotes. This matters for JSON-shaped `notes` or other structured values.

```csv theme={null}
phone_number,first_name,notes
+919876543210,Rahul,"{""plan"":""gold"",""city"":""Pune""}"
```

## Numbers On The DNC List

The [workspace DNC list](https://dialnexa.com/docs/platform/dnc-list.md) excludes listed numbers from the upload preview. The dashboard shows how many rows were left out; these are blocked contacts, not invalid phone numbers to repair. Compare the skip notice with the accepted recipient count before launching.

If a number is added to the DNC list after upload, DialNexa checks it again before dialing and does not retry it. Remove a number from the list only when your team intends to allow future calls to it.

## Upload Wizard Steps

The batch upload wizard keeps each review step explicit before the recipient table is accepted.

| Step | What the operator checks |
| - | - |
| Match CSV Columns | Confirms the phone-number column, expected dynamic variables, defaulted values, and extra columns. |
| AI Name Cleanup | Optionally chooses a name column, then asks Claude for cleaner first-name suggestions for batches with up to `2,100` contacts. |
| Review Invalid Phone Numbers | Shows rows that failed destination validation so the operator can edit or remove them before launch. |
| Finish | Accepts the current reviewed file and closes the wizard when no invalid rows remain. |

If a new upload is cancelled during review, DialNexa restores the previous recipient state instead of leaving a partial file attached to the campaign.

While a wizard step is processing, the close button is disabled and clicking outside the dialog does not close it. Wait for the active step to finish. At other times, use the explicit close button or the step action so the wizard can restore the previous recipient state correctly.

## Template Behavior

The download template changes with the selected agent and version.

> [card] [Agent defaults first](https://dialnexa.com/docs/agents/dynamic-variables.md)
>
> The template uses default dynamic variable keys from the selected agent version when available.

> [card] [Fallback placeholders](https://dialnexa.com/docs/data/default-variables.md)
>
> If no agent variables are available, the template includes generic placeholder variable columns.

> [card] [Recipient preview](https://dialnexa.com/docs/batch-calls/recipient-results.md)
>
> Parsed recipients are displayed in a table before launch.

> [card] [File upload checks](https://dialnexa.com/docs/batch-calls/common-upload-errors.md)
>
> The page validates CSV type and rejects large or invalid uploads.

## Match Uploaded Columns

After upload, the **Match CSV Columns** modal lets you align the file with the selected agent version before the table is created.

![DialNexa Match CSV Columns modal showing phone number mapping, dynamic variable defaults, unmapped fields, and the confirm action.](https://mintcdn.com/dialnexa/HOnVBqIHk6o8-0eg/images/documentation/screenshots/batch-csv-mapping-modal.png?fit=max\&auto=format\&n=HOnVBqIHk6o8-0eg\&q=85\&s=d65e96ff87d2f7bc9a6eeefc6272dd86)

| Modal area | Behavior |
| - | - |
| Phone number | Auto-detects common headers such as `phone`, `mobile`, `contact_number`, or `telephone`. You can choose a different column if needed. |
| Dynamic variables | Auto-matches exact, case-insensitive, and normalized header names for expected variables. |
| Defaults | Shows agent default values next to variables that have fallbacks. |
| Unmapped fields | Warns when expected variables are not mapped. Defaults are used where available, otherwise values are empty. |
| Extra columns | Shows columns that will remain visible in the table but will not be used during calls. |

When you confirm the mapping, DialNexa normalizes the selected phone column to `phonenumber` and renames mapped variable columns to the expected agent variable keys. This lets operators upload files with readable business headers without editing the source spreadsheet first.

The CSV parser keeps quoted multiline fields together and reports physical file row numbers, so row notices match the lines users see in a spreadsheet. It can automatically rejoin an unquoted JSON object or array that was split by its own comma or line break when the reconstructed value parses as valid JSON. The create page shows an informational notice for those repaired rows and rewrites the accepted file with correct quoting.

| File notice | What to do |
| - | - |
| Repaired JSON rows | Review the listed rows, then quote those values in the source file before the next upload. |
| Rejoined value is not valid JSON | Inspect the listed rows before launch. The column count was repaired, but DialNexa cannot prove the value is correct. |
| More values than header columns | Add a missing header or quote the value containing a comma. The upload stops instead of guessing which column owns the extra value. |
| Excel data under a blank header | Add a header in row `1` if the value is needed. DialNexa skips data in unnamed Excel columns and shows the affected rows. |

Short rows are padded with empty trailing values. Extra empty cells caused only by a trailing comma are ignored. A malformed row with unresolved extra data blocks the upload and reports up to the first affected row numbers.

## Review AI Name Suggestions

After column mapping, the wizard opens an optional AI Name Cleanup step. The dashboard can auto-select a likely name column, but the operator can choose a different column or skip the step. If a column is selected and the file has up to `2,100` leads, Claude checks the names for cleanup suggestions before the recipient table is built. If name cleanup fails, DialNexa shows an empty review state and continues with the original names.

The **Review AI Name Suggestions** modal shows the original value, the suggested value, and row-level controls.

![DialNexa Review AI Name Suggestions modal showing original names, AI suggestions, row actions, Download CSV, and Proceed.](https://mintcdn.com/dialnexa/deSh6R4VHhcuER-T/images/documentation/screenshots/batch-name-review-modal.png?fit=max\&auto=format\&n=deSh6R4VHhcuER-T\&q=85\&s=160fe42eacab8ed9a0dbf329dcf9b6c3)

| Control | Behavior |
| - | - |
| Accept | Uses the suggested clean name for that row. |
| Reject | Keeps the original uploaded name. |
| Edit | Lets the operator type a custom replacement. |
| Accept All or Reject All | Applies the same decision to every suggested row. |
| Download CSV | Downloads a reviewed CSV before proceeding. |
| Proceed | Applies accepted or edited names, then continues recipient parsing. |
| Skip | Bypasses AI name cleanup and continues to phone-number validation. |

For batches over `2,100` contacts, the dashboard skips AI name cleanup and shows a warning. Review names in the source file before upload when large campaigns need standardized salutations.

## Convert Names To Devanagari

For a Hindi-speaking agent, the name-cleanup step offers **Convert to Devanagari** after you select a name column. Use it when the agent should pronounce names from Hindi-script values rather than Latin-script spellings.

1. Select the name column and enable **Convert to Devanagari**.
2. Review the original name, cleaned suggestion, and **Devanagari** value together.
3. Accept a suggestion to use its converted value, or reject it to keep the original uploaded name. Review every name whose pronunciation matters.
4. If you edit a cleaned name, choose **Re-check N edited names** to regenerate its conversion before proceeding. Download is unavailable while edited names still need rechecking.
5. Continue with **Proceed** after resolving the pending rows.

If conversion is unavailable or a row has no converted value, review the retained cleaned name yourself. A successful cleanup does not guarantee a successful script conversion. If an edited row cannot be rechecked, reject it to keep its original name and clear its pending conversion.

## Review Invalid Phone Numbers

After mapping and name review, the dashboard validates the selected phone column against the outbound route. Invalid rows open the **Review Invalid Phone Numbers** step.

![DialNexa Review Invalid Phone Numbers modal showing an unresolved phone number, validation suggestion, edit and remove actions, Download CSV, and Finish.](https://mintcdn.com/dialnexa/j4YElRgYrHSfuXTP/images/documentation/screenshots/batch-invalid-phone-numbers-modal.png?fit=max\&auto=format\&n=j4YElRgYrHSfuXTP\&q=85\&s=2333f1dff4ac0eea59f039aacfb333c7)

| Action | Behavior |
| - | - |
| Edit | Corrects the number in that row and validates the file again. |
| Remove | Drops that row from the batch. Rows left unresolved are removed by default. |
| Remove All | Marks every invalid row for removal. |
| Download CSV | Downloads the current invalid-row decisions for offline review. |
| Finish | Accepts the file once the invalid-row list is empty. |

Each invalid row keeps its original source row number, mapped phone value, validation message, and current decision. This matters when a spreadsheet owner needs to repair the source file later, because the operator can point to the exact row instead of describing a general upload failure.

| Row state | Result |
| - | - |
| Corrected and valid | The row stays in the batch with the corrected number. |
| Corrected but still invalid | The row remains in review with the latest validation reason. |
| Removed | The row is excluded from the recipient table. |
| Left unresolved | The row is removed by default before the reviewed file is accepted. |
| Downloaded for review | The CSV reflects the current edit or remove decisions so cleanup can continue outside DialNexa. |

DialNexa can normalize Indian numbers that explicitly include the `91`, `+91`, or `0091` country code. It does not guess that a bare `10` digit number is Indian, because that could rewrite a real number from another country. Use full international format when possible.

## Add A Country Code To Multiple Rows

In **Review Invalid Phone Numbers**, **Add country code** appears when rows are eligible for a bulk correction. Use it only when you know those local numbers belong to the selected country.

1. Select the country code.
2. Check the number of eligible rows shown by **Apply to N rows**, then apply it.
3. Review the corrected values and the result summary. Already international numbers, empty or unreadable values, and rows you edited manually are excluded from the bulk change.
4. Choose **Finish** to submit the current corrections for validation. Correct any remaining invalid numbers before accepting the file.

Changing the selected country recalculates bulk corrections from each original number. It does not overwrite manual edits. Adding a prefix alone does not prove that a number is valid for the outbound route.

When **Skip duplicate phone numbers** is enabled, bulk correction also checks for collisions with valid recipients and retained manual edits. Duplicate rows can be marked for removal. Finish checks the reviewed values again and removes duplicates before continuing. Check the final recipient count so you know which rows remain.

## Duplicate Phone Number Handling

The create page skips duplicate phone numbers by default before the recipient table is built. When the same non-empty phone number appears more than once, DialNexa keeps the first mapped row and removes later rows with that number. After upload, the page shows how many duplicate phone numbers were skipped.

| Control | Behavior |
| - | - |
| Skip duplicate phone numbers | Enabled by default before file upload. Leave it on when each phone number should receive one call. |
| Duplicate non-empty phone numbers | Only the first mapped row for that number is kept. Later rows are removed before campaign parsing. |
| Empty phone numbers | Rows without a phone number still pass through so backend validation can report the missing value. |
| Changing the duplicate setting | Remove the uploaded file first, then turn the setting on or off before uploading again. |

Turn duplicate skipping off only when repeated calls to the same phone number are intentional for that campaign.

## Prepare A Clean File

**1. Enter a short campaign title**

Keep the title at `35` characters or fewer. Longer titles are rejected before launch.

**2. Select the outbound number first**

This lets the page know which agent version variables to use.

**3. Download the template**

Start with headers that match the selected agent.

**4. Fill realistic values**

Use production-ready names, dates, amounts, and transfer destinations.

**5. Upload and inspect rows**

Check the preview table before saving or starting.

**6. Fix errors before launch**

Do not launch a file whose preview already looks wrong.

## File Requirements

| Requirement | Value |
| - | - |
| File type | CSV or Excel |
| Maximum file size | 10 MB |
| Structure | One recipient per row, headers matching the downloaded template or mapped in the upload modal |
| Structured values | Valid JSON objects must be quoted as one CSV cell when they contain commas, quotes, or line breaks |

## When Rows Fail Validation

The upload parser checks recipient phone numbers against the same [destination validation rules](https://dialnexa.com/docs/calls/phone-numbers.md#outbound-destination-validation) used by single outbound calls. Duplicate removal happens before this validation when **Skip duplicate phone numbers** is enabled. Failed rows appear in the phone-number review step, grouped with the validation reason. See [Common Upload Errors](https://dialnexa.com/docs/batch-calls/common-upload-errors.md) for each error type, what it means, and how to fix the file.

## Download The Errors CSV

When an upload is rejected because more than three rows fail validation, the file is not accepted and the upload area shows **Some rows could not be used** with a **Download errors CSV** button. With three or fewer failures, the reasons appear in the error message instead.

The download, `batch-call-errors.csv`, has one row per failed recipient:

| Column | Meaning |
| - | - |
| `position` | Row number of the recipient in the uploaded file |
| `phone_number` | The phone number as it appeared in that row |
| `failed_parsing_reason` | Why the row failed validation |

The button works once. After one download it disappears, and it is also cleared when you choose another file or remove the current one, so save the report before you retry. Fix the listed rows in the source file, then upload it again.

## Avoid Column Mapping Collisions

Two mapped columns cannot share the same final field name. If a mapped field collides with an unmapped source column, the mapped column wins and the extra column is dropped. Review the resulting recipient table before launch.

Duplicate removal uses the phone column you selected, including in Excel files. A raw column with a similar name does not override your selection. Numeric Excel phone cells are converted to strings before validation; use text cells with complete international numbers to preserve leading digits.

## Verify The Recipient File

After upload, confirm the phone-number column, variable mappings, row count, duplicate handling, and validation results. Run a small batch and verify that spoken values match the intended CSV row.

## When AI Name Cleanup Cannot Check Every Name

Name cleanup is optional. If the service cannot check some names, the dashboard warns how many were left unchanged while keeping usable suggestions for the others. Review those unchanged names yourself before proceeding.

If cleanup is unavailable or the response cannot be matched safely to the uploaded rows, the review reports the failure and keeps the original names. You can continue with them or correct the source file and try again. An unavailable check does not mean that every name is already correct.

## Download the selected version template

Select the agent and published version before downloading the CSV template. The template combines variable names used in that version's prompt, welcome message, voicemail message, and default variables. It retains `agent_transfer_destinations` for Conversational Flow transfer routing. Helper expressions are not column names. After switching versions, download a fresh template and review the mappings again.

## Related Reading

> [card] [Dynamic Variables](https://dialnexa.com/docs/agents/dynamic-variables.md)
>
> Map variables to CSV columns.

> [card] [Common Upload Errors](https://dialnexa.com/docs/batch-calls/common-upload-errors.md)
>
> Fix file issues.

> [card] [Recipient Results](https://dialnexa.com/docs/batch-calls/recipient-results.md)
>
> Review row outcomes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.