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

# Create Batch Call

> Use the create_batch_call MCP tool on the DialNexa remote MCP server.

<span data-api-safety-label="billable"><Badge color="yellow" size="sm" shape="pill">Billable - retry unsafe</Badge></span>

Creates a batch call campaign from a small lead list and starts dialing real phone numbers immediately. This is NOT a read-only action, spends real money, and cannot be undone once calls go out (the campaign itself can be cancelled afterward with update\_batch\_call\_status, but any calls already placed are not). Requires confirm: true — only set this after the user has explicitly approved starting this specific batch, never preemptively. Only suitable for short lists (a few dozen leads at most) — for larger campaigns, tell the user to use the dashboard upload instead. Recommended order: clean\_batch\_call\_names on the name column, then preview\_batch\_call\_leads on the file, resolve any issues with the user, THEN call this. file\_base64 must be the base64-encoded content of a CSV or Excel file with a phone\_number column (and optionally name/other columns as dynamic variables). agent\_version\_number is required in practice — omitting it fails with "no outbound phone number found," since the org's phone number is bound to a specific agent+version pair, not just the agent. Use get\_agent or list\_agent\_versions first to find the right version\_number.

## Parameters

| Name                   | Type      | Required | Description                                                                                                                                                   |
| ---------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`                | `string`  | Yes      | Campaign title                                                                                                                                                |
| `agent_id`             | `string`  | Yes      | The agent ID to use for calls, e.g. agent\_abc123                                                                                                             |
| `agent_version_number` | `string`  | Yes      | Required in practice — the specific published agent version whose bound phone number will be used to dial. Get this from get\_agent or list\_agent\_versions. |
| `file_name`            | `string`  | Yes      | File name with extension, e.g. leads.csv or leads.xlsx                                                                                                        |
| `file_base64`          | `string`  | Yes      | Base64-encoded content of a small (few dozen rows) CSV/Excel leads file                                                                                       |
| `starts_at`            | `string`  | No       | ISO 8601 datetime to start calling; omit to start immediately                                                                                                 |
| `calling_hours_start`  | `string`  | No       | HH:mm — earliest time of day to call                                                                                                                          |
| `calling_hours_end`    | `string`  | No       | HH:mm — latest time of day to call                                                                                                                            |
| `confirm`              | `boolean` | Yes      | Must be true. Set this only after the user has explicitly approved starting this specific batch call.                                                         |

## Before you call

* Connect and initialize the MCP client with OAuth or an API key for the intended workspace.
* Provide the required parameters: `title`, `agent_id`, `agent_version_number`, `file_name`, `file_base64`, `confirm`.
* Set `confirm: true` only after the user approves the exact target and action.

## Example MCP request

Send `tools/call` after your client completes MCP initialization. Replace placeholder values with IDs and inputs from your workspace. For object and array parameters, follow the nested requirements in the parameter description instead of treating an empty value as complete.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_batch_call",
    "arguments": {
      "title": "Example resource",
      "agent_id": "agent_abc123",
      "agent_version_number": "1",
      "file_name": "VALUE",
      "file_base64": "BASE64_ENCODED_CSV",
      "confirm": true
    }
  }
}
```

The server returns one text content block. Parse `content[0].text` as JSON when the tool succeeds. See [MCP responses and errors](/docs/mcp-tools/errors) for the full envelope and failure behavior.

## Verify the result

Store the returned resource ID and confirm the response is not marked `isError`. Call [Get Agent](/docs/mcp-tools/agents/get-agent) to read the affected resource. Verify the call, batch, or purchase state before retrying.

## Retry safety

This tool can spend wallet balance or start real calls. After a timeout, inspect the relevant resource before retrying so you do not duplicate the action.

## Related MCP tools

* [Get Agent](/docs/mcp-tools/agents/get-agent): `get_agent`
* [List Agent Versions](/docs/mcp-tools/agents/list-agent-versions): `list_agent_versions`
* [Clean Batch Call Names](/docs/mcp-tools/batch-calls/clean-batch-call-names): `clean_batch_call_names`
* [Preview Batch Call Leads](/docs/mcp-tools/batch-calls/preview-batch-call-leads): `preview_batch_call_leads`
* [Update Batch Call Status](/docs/mcp-tools/batch-calls/update-batch-call-status): `update_batch_call_status`
* [List Batch Calls](/docs/mcp-tools/batch-calls/list-batch-calls): `list_batch_calls`
* [List Calls In Batch](/docs/mcp-tools/batch-calls/list-calls-in-batch): `list_calls_in_batch`

## Related guides

* [Connect to the DialNexa MCP server](/docs/mcp-tools/overview)
* [Batch Calls MCP tools](/docs/mcp-tools/batch-calls/overview)
* [MCP responses and errors](/docs/mcp-tools/errors)